squash: purge data files from history

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,39 @@
+---
+title: Marathon Live Matcher
+emoji: 🌍
+colorFrom: green
+colorTo: gray
+sdk: gradio
+sdk_version: 6.19.0
+app_file: app.py
+pinned: false
+short_description: Market fit, 30s snippet picks and metadata tags
+---
+
+# Marathon — live matcher
+
+Upload a track and get, on one screen:
+
+1. **Where it fits.** The track's audio fingerprint against every sound
+   charting in each market this week — nearest records named, with
+   place / derive / pass verdicts and the denominators behind them.
+2. **Snippet recommendations.** A 30-second window slid across the track at a
+   5-second hop, ranked by how close each window sits to the trend pools the
+   track already fits, blended with a musical-boundary score. This is the
+   official clip a label must pick when delivering to TikTok / YouTube /
+   Meta through a distributor.
+3. **Suggested tags.** CLAP zero-shot descriptors plus trend-derived context,
+   as a copy-paste line for distributor metadata forms.
+
+**Gated.** Nothing runs without the team passphrase
+(`MARATHON_LIVE_PASSPHRASE`, a Space secret). Uploads are analysed in memory
+and never stored or published.
+
+Everything here is descriptive. Similarity measures how close two recordings
+sound; it is not a prediction that a record will perform. Cutoffs are
+first-pass and calibrated on US/global data. The corpus is one week of
+charts — no trajectory, no momentum claims.
+
+Built from `marathon/live_space/` and deployed by
+`python -m marathon.cli deploy-live`. The corpus files are written by
+`python -m marathon.cli export-live`.

analysis.py

@@ -0,0 +1,109 @@
+"""One upload → the whole answer. No UI, no Gradio: importable and runnable
+headless, which is how the end-to-end verification runs before deploy.
+
+Order matters for RAM on a small box: the audio is loaded once at 48 kHz for
+CLAP, the beat analysis reloads it at 22.05 kHz (librosa's own cache-free
+path), and the CLAP tile cache is dropped as soon as the vectors exist.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+import boundaries
+import clap_embed
+import livematch
+import tags as tagmod
+
+WINDOW_S = 30.0          # the official clip length a distributor asks for
+HOP_S = clap_embed.GRID_S
+
+
+def analyse_track(path: str, embedder, corpus: livematch.Corpus,
+                  vocab=None, top_markets: int = 8, focus_markets: int = 3,
+                  snippet_top: int = 4) -> dict:
+    audio = clap_embed.load_audio(path)
+    duration = len(audio) / clap_embed.CLAP_SR
+
+    track_vec = embedder.embed_track(audio)
+    scan = livematch.rank_regions(corpus, track_vec, top=5)
+    ranked_isos = sorted(scan["regions"], key=lambda k: -scan["regions"][k]["best"])
+    shown = ranked_isos[:top_markets]
+    focus = ranked_isos[:focus_markets]
+
+    # -- snippets ---------------------------------------------------------
+    starts, wvecs = embedder.embed_windows(audio, WINDOW_S, HOP_S)
+    embedder.reset_cache()
+
+    per_market = {}
+    if starts and focus:
+        for iso in focus:
+            idx = np.asarray(corpus.regions[iso]["idx"], dtype=np.int64)
+            sims = wvecs @ corpus.emb[idx].T          # (windows, pool)
+            best = sims.argmax(axis=1)
+            per_market[iso] = {
+                "best_sim": sims.max(axis=1),
+                "best_sound": [int(idx[b]) for b in best],
+            }
+    if per_market:
+        stack = np.stack([per_market[i]["best_sim"] for i in focus])
+        win_best_market = [focus[int(j)] for j in stack.argmax(axis=0)]
+        affinity = stack.max(axis=0).tolist()
+    else:
+        win_best_market = [None] * len(starts)
+        affinity = [0.0] * len(starts)
+
+    beat = boundaries.analyse(path)
+    wscores = boundaries.window_scores(beat, starts, WINDOW_S)
+    picks = livematch.rank_windows(affinity, wscores["boundary"], starts,
+                                   top=snippet_top)
+    by_start = {round(s, 2): i for i, s in enumerate(starts)}
+    for p in picks:
+        i = by_start[p["start_s"]]
+        iso = win_best_market[i]
+        p["end_s"] = round(p["start_s"] + WINDOW_S, 2)
+        p["market"] = iso
+        p["market_name"] = corpus.regions[iso]["name"] if iso else None
+        p["on_downbeat"] = wscores["on_downbeat"][i]
+        p["nearest_downbeat"] = wscores["nearest_downbeat"][i]
+        if iso:
+            s = corpus.sounds[per_market[iso]["best_sound"][i]]
+            p["nearest"] = {"artist": s["artist"], "title": s["title"],
+                            "deezer_id": s.get("deezer_id")}
+        else:
+            p["nearest"] = None
+
+    # -- tags -------------------------------------------------------------
+    # nearest neighbours by index, straight from the focus pools
+    neighbour_idx: list[int] = []
+    if focus:
+        pool = livematch.pool_index(corpus, focus)
+        sims = corpus.emb[pool] @ track_vec
+        neighbour_idx = [int(pool[i]) for i in np.argsort(-sims)[:10]]
+    trend = tagmod.trend_tags(scan["regions"], shown, corpus.sounds, neighbour_idx)
+    model_tags, copy = None, None
+    if vocab is not None:
+        model_tags = vocab.top(track_vec)
+        copy = tagmod.copy_line(model_tags, trend)
+    else:
+        copy = ", ".join((trend.get("genres") or [])
+                         + [m["iso"] for m in trend["markets"][:5]])
+
+    return {
+        "duration_s": round(duration, 1),
+        "week": scan["week"],
+        "shown_markets": shown,
+        "focus_markets": focus,
+        "regions": scan["regions"],
+        "track_vec": track_vec,
+        "snippets": picks,
+        "window_count": len(starts),
+        "beat": {"ok": beat.get("ok"), "tempo": beat.get("tempo"),
+                 "error": beat.get("error")},
+        "tags": {"model": model_tags, "trend": trend, "copy_line": copy},
+        "corpus": {"week": corpus.week, "sounds": len(corpus.sounds),
+                   "regions": len(corpus.regions),
+                   "generated_at": corpus.meta.get("generated_at"),
+                   "sources": corpus.meta.get("sources", []),
+                   "genre_labelled": corpus.meta.get("genre_labelled_sounds", 0)},
+    }

app.py

@@ -0,0 +1,182 @@
+"""Marathon — live matcher. Upload a track, get the world scan, the 30-second
+snippet shortlist and metadata tags, in one screen.
+
+Gated: the Space repo can be public because nothing runs without the team
+passphrase, which lives only in the Space secret MARATHON_LIVE_PASSPHRASE
+(same value as the drop sheet's). No passphrase set → the app refuses to
+analyse anything rather than silently serving an open endpoint.
+
+The corpus (corpus.npz + corpus.json) is this week's scan exported by
+`marathon.cli export-live`. It is NOT in this public repo: it lives in the
+private dataset repo kalamishere/marathon-corpus and is fetched at startup
+with the HF_TOKEN Space secret, so repo browsers see code but no data.
+Local dev keeps working: files already present next to app.py win.
+No database, no network at match time.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+import soundfile as sf
+
+import analysis
+import clap_embed
+import livematch
+import render
+import tags as tagmod
+
+HERE = Path(__file__).resolve().parent
+CORPUS_DATASET = "kalamishere/marathon-corpus"
+
+
+def _fetch_corpus(dest: Path) -> Path:
+    """Fetch corpus files from the private dataset repo unless they are
+    already present locally (dev checkout / staged verify dir)."""
+    if (dest / "corpus.npz").exists() and (dest / "corpus.json").exists():
+        return dest
+    from huggingface_hub import hf_hub_download
+
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        raise RuntimeError(
+            "corpus files missing and HF_TOKEN not set — cannot fetch "
+            f"{CORPUS_DATASET}")
+    for name in ("corpus.npz", "corpus.json"):
+        got = hf_hub_download(repo_id=CORPUS_DATASET, filename=name,
+                              repo_type="dataset", token=token)
+        (dest / name).unlink(missing_ok=True)
+        (dest / name).symlink_to(got)
+    return dest
+
+
+CORPUS = livematch.Corpus.load(_fetch_corpus(HERE))
+PASSPHRASE = os.environ.get("MARATHON_LIVE_PASSPHRASE", "")
+MAX_SNIPPETS = 4
+
+_state = {"embedder": None, "vocab": None, "zero_shot_ok": None}
+
+
+def _embedder():
+    """Loaded on first analysis, not at import: the Space should show its gate
+    immediately rather than after a two-gigabyte checkpoint download."""
+    if _state["embedder"] is None:
+        emb = clap_embed.Embedder()
+        _state["embedder"] = emb
+        try:
+            _state["vocab"] = tagmod.TagVocab(emb)
+        except Exception as exc:  # text tower missing → group two only
+            print(f"[tags] text tower unavailable, zero-shot disabled: {exc}")
+            _state["vocab"] = None
+    return _state["embedder"]
+
+
+def _clip(path: str, start_s: float, end_s: float, out_dir: str) -> str:
+    """A real slice of the uploaded file, written out so the browser can play
+    it. Original sample rate and channels — the point is to judge the clip.
+
+    MP3 where libsndfile can write it: four 30-second stereo WAVs is ~23 MB
+    down a phone connection, and this is a listening check, not a master.
+    """
+    info = sf.info(path)
+    sr = info.samplerate
+    data, _ = sf.read(path, start=int(start_s * sr), stop=int(end_s * sr),
+                      dtype="float32")
+    stem = os.path.join(out_dir, f"snippet_{int(start_s)}-{int(end_s)}")
+    try:
+        out = stem + ".mp3"
+        sf.write(out, data, sr, format="MP3")
+        return out
+    except Exception:
+        out = stem + ".wav"
+        sf.write(out, data, sr)
+        return out
+
+
+def run(passphrase: str, audio_path: str, progress=gr.Progress()):
+    blanks = [gr.update(value=None, visible=False)] * MAX_SNIPPETS
+    if not PASSPHRASE:
+        return ("<p><b>This Space has no passphrase configured.</b> Set the "
+                "MARATHON_LIVE_PASSPHRASE secret before use.</p>", *blanks)
+    if not hmac.compare_digest((passphrase or "").strip(), PASSPHRASE):
+        return ("<p>Wrong passphrase.</p>", *blanks)
+    if not audio_path:
+        return ("<p>Choose an audio file (mp3, wav, m4a) to analyse.</p>", *blanks)
+
+    progress(0.05, desc="loading the model")
+    emb = _embedder()
+    progress(0.25, desc="listening to the track")
+    res = analysis.analyse_track(audio_path, emb, CORPUS, vocab=_state["vocab"],
+                                 snippet_top=MAX_SNIPPETS)
+    progress(0.85, desc="cutting snippets")
+    label = Path(audio_path).stem
+    html = render.render(res, label)
+
+    tmp = tempfile.mkdtemp(prefix="marathon_snips_")
+    players = []
+    for i in range(MAX_SNIPPETS):
+        if i < len(res["snippets"]):
+            p = res["snippets"][i]
+            try:
+                clip = _clip(audio_path, p["start_s"], p["end_s"], tmp)
+            except Exception as exc:
+                print(f"[clip] {exc}")
+                players.append(gr.update(value=None, visible=False))
+                continue
+            mk = f' · closest to {p["market"]}' if p["market"] else ""
+            players.append(gr.update(
+                value=clip, visible=True,
+                label=f'{i + 1} · {livematch.fmt_time(p["start_s"])}–'
+                      f'{livematch.fmt_time(p["end_s"])}{mk} · '
+                      f'{p["affinity"] * 100:.0f}%'))
+        else:
+            players.append(gr.update(value=None, visible=False))
+    return (html, *players)
+
+
+CSS = """
+footer { display: none !important; }
+#intro h1 { font-size: 21px; margin: 0 0 4px; letter-spacing: -.01em; }
+#intro p { font-size: 13.5px; color: #55534e; margin: 0 0 2px; }
+/* Gradio's upload widget renders differently across versions; rather than
+   fight its internals we hide the stock copy and write our own prompt. */
+#up .wrap, #up .source-selection { min-height: 0; }
+#up .wrap span, #up .wrap p { display: none; }
+#up .wrap::after { content: "Tap to choose an audio file — mp3, wav or m4a";
+  font-size: 14px; color: #55534e; }
+@media (max-width: 640px) { .gradio-container { padding: 8px !important; } }
+"""
+
+# Gradio 6 moved `theme` and `css` off the Blocks constructor onto launch().
+with gr.Blocks(title="Marathon — live matcher") as demo:
+    gr.HTML(
+        '<div id="intro"><h1>Marathon — live matcher</h1>'
+        '<p>Upload a track: where it sits against what is charting in each '
+        'market this week, which 30 seconds to deliver as the official clip, '
+        'and tags for the metadata form.</p>'
+        f'<p>Corpus: {CORPUS.week} · {len(CORPUS.sounds):,} charting sounds · '
+        f'{len(CORPUS.regions)} markets.</p></div>')
+    pw = gr.Textbox(label="Team passphrase", type="password",
+                    placeholder="the passphrase you were sent")
+    audio = gr.Audio(label="Track", sources=["upload"], type="filepath",
+                     elem_id="up")
+    go = gr.Button("Analyse", variant="primary")
+    out = gr.HTML()
+    snips = [gr.Audio(label=f"Snippet {i + 1}", visible=False,
+                      interactive=False)
+             for i in range(MAX_SNIPPETS)]
+    # Named so the deploy check can drive the real Space the way a browser
+    # does. Exposing it is safe: every path through `run` checks the
+    # passphrase first, and there is nothing to reach without one.
+    go.click(run, inputs=[pw, audio], outputs=[out, *snips],
+             api_name="analyse")
+
+if __name__ == "__main__":
+    demo.queue(max_size=8).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", "7860")),
+        css=CSS, theme=gr.themes.Soft())

boundaries.py

@@ -0,0 +1,135 @@
+"""Where a 30-second clip should START — the musical half of the snippet pick.
+
+Adapted from audio-brief's `cutpoints.py` (v1, language-agnostic, no ASR),
+© the same project, vendored here rather than imported because audio-brief is
+a separate deployed Space and is not modified by this build.
+
+Two things are kept from cutpoints and one is dropped:
+
+  kept  · downbeat phase picked by LOW-BAND (kick) onset energy, so "starts on
+          a downbeat" means the real 4/4 phase, not every 4th beat from an
+          arbitrary offset.
+  kept  · per-beat hook score from recurrence COUNT (position-neutral, so the
+          first chorus is not penalised for arriving early) plus RMS energy.
+  drop  · the demucs vocal stem. cutpoints weights it at 0.35, but demucs is a
+          second model and several hundred MB of RAM; on a free CPU Space that
+          is the difference between working and not. Its weight is folded into
+          repetition and energy, and the UI reports the omission.
+
+Weights are HAND-SET AND UNFIT — the same status cutpoints reports for its
+own. They order candidate windows; they are not a measurement of anything.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+SR = 22050
+HOP = 512
+W_REP, W_ENE = 0.65, 0.35     # hand-set, unfit; cutpoints' vocal weight folded in
+
+# The roster this Space serves is Afrobeats-leaning, where librosa's 120 BPM
+# default prior tends to lock onto a half-time or triplet reading. 110 is a
+# genre-matched prior, not a measurement — the detected tempo is reported so a
+# wrong lock is visible rather than silent.
+START_BPM = 110.0
+
+
+def _norm(x: np.ndarray) -> np.ndarray:
+    x = np.asarray(x, dtype=np.float64)
+    lo, hi = float(np.min(x)), float(np.max(x))
+    return (x - lo) / (hi - lo) if hi - lo > 1e-9 else np.zeros_like(x)
+
+
+def _norm_rows(m):
+    m = np.asarray(m, dtype=np.float64)
+    return (m - m.mean(axis=1, keepdims=True)) / (m.std(axis=1, keepdims=True) + 1e-9)
+
+
+def analyse(path: str) -> dict:
+    """-> {tempo, beat_times, downbeat_times, score (per beat), ok}.
+
+    Never raises: a track the beat tracker cannot read still gets snippets,
+    ranked on trend affinity alone, with `ok: False` so the UI can say so.
+    """
+    try:
+        return _analyse(path)
+    except Exception as exc:  # noqa: BLE001 — degradation is the feature
+        return {"ok": False, "error": f"{type(exc).__name__}: {exc}",
+                "tempo": None, "beat_times": [], "downbeat_times": [],
+                "score": []}
+
+
+def _analyse(path: str) -> dict:
+    import librosa
+
+    y, sr = librosa.load(path, sr=SR, mono=True)
+    tempo, beat_frames = librosa.beat.beat_track(
+        y=y, sr=sr, hop_length=HOP, trim=False, start_bpm=START_BPM)
+    beat_times = librosa.frames_to_time(beat_frames, sr=sr, hop_length=HOP)
+    if len(beat_times) < 8:
+        raise ValueError("too few beats")
+
+    # 4/4 phase from kick-band onset energy (cutpoints._downbeat_phase)
+    mel = librosa.feature.melspectrogram(y=y, sr=sr, hop_length=HOP,
+                                         n_mels=16, fmax=200)
+    onset_low = librosa.onset.onset_strength(
+        S=librosa.power_to_db(mel), sr=sr, hop_length=HOP)
+    bf = np.clip(beat_frames, 0, len(onset_low) - 1)
+    beat_onset = onset_low[bf]
+    phase = int(np.argmax([
+        float(np.mean(beat_onset[p::4])) if len(beat_onset[p::4]) else 0.0
+        for p in range(4)]))
+    downbeat_times = [float(beat_times[i])
+                      for i in range(phase, len(beat_times), 4)]
+
+    # hook score: recurrence count + energy, smoothed over a bar
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr, hop_length=HOP)
+    mfcc = librosa.feature.mfcc(y=y, sr=sr, hop_length=HOP, n_mfcc=13)
+    feat = np.vstack([
+        _norm_rows(librosa.util.sync(chroma, beat_frames, aggregate=np.median)),
+        _norm_rows(librosa.util.sync(mfcc, beat_frames, aggregate=np.mean))])
+    aff = librosa.segment.recurrence_matrix(feat, mode="affinity", sym=True, width=9)
+    nz = aff[aff > 0]
+    rep = (np.zeros(aff.shape[0]) if nz.size == 0
+           else (aff > float(np.percentile(nz, 75))).astype(np.float64).sum(axis=1))
+    rms = librosa.feature.rms(y=y, hop_length=HOP)[0]
+    ene = librosa.util.sync(rms[np.newaxis, :], beat_frames, aggregate=np.mean)[0]
+    n = min(len(rep), len(ene), len(beat_times))
+    score = W_REP * _norm(rep[:n]) + W_ENE * _norm(ene[:n])
+    score = np.convolve(score, np.ones(4) / 4, mode="same")
+
+    return {"ok": True, "tempo": round(float(np.atleast_1d(tempo)[0]), 1),
+            "beat_times": [float(t) for t in beat_times[:n]],
+            "downbeat_times": downbeat_times,
+            "score": [float(x) for x in score]}
+
+
+def window_scores(an: dict, starts: list[float], window_s: float = 30.0) -> dict:
+    """-> {boundary: [...0-1...], on_downbeat: [...], nearest_downbeat: [...]}.
+
+    boundary = half "does it start on the downbeat grid", half "is the window
+    inside the recurring, high-energy part of the record". With no beat track
+    every window scores 0.5 — neutral, so affinity alone decides.
+    """
+    if not an.get("ok") or not an.get("downbeat_times"):
+        return {"boundary": [0.5] * len(starts),
+                "on_downbeat": [None] * len(starts),
+                "nearest_downbeat": [None] * len(starts)}
+    db = np.asarray(an["downbeat_times"], dtype=np.float64)
+    bt = np.asarray(an["beat_times"], dtype=np.float64)
+    sc = np.asarray(an["score"], dtype=np.float64)
+    sec_per_beat = float(np.median(np.diff(bt))) if len(bt) > 1 else 0.5
+    tol = 2.0 * sec_per_beat          # within half a bar counts as aligned
+
+    boundary, on_db, near = [], [], []
+    for s in starts:
+        d = float(np.min(np.abs(db - s)))
+        align = max(0.0, 1.0 - d / tol) if tol > 0 else 0.0
+        sel = (bt >= s) & (bt < s + window_s)
+        hook = float(np.mean(sc[sel])) if sel.any() else 0.0
+        boundary.append(round(0.5 * align + 0.5 * hook, 4))
+        on_db.append(round(align, 3))
+        near.append(round(float(db[int(np.argmin(np.abs(db - s)))]), 2))
+    return {"boundary": boundary, "on_downbeat": on_db,
+            "nearest_downbeat": near}

clap_embed.py

@@ -0,0 +1,156 @@
+"""CLAP audio + text embedding for the live matcher Space.
+
+The tiling here is a deliberate, line-by-line reimplementation of
+audio-brief's `clap_worker.py::_embed` (checkpoint `default-630k`,
+HTSAT-tiny, enable_fusion=False, librosa.load(sr=48000, mono=True), 10 s
+consecutive tiles, mean, L2). That worker produced every vector in the
+exported corpus. If this file drifts from it, every similarity in the app
+becomes quietly wrong while still looking plausible — so `cli verify-live`
+re-embeds a known corpus track through this code and compares against its
+stored database vector before anything ships.
+
+Two things beyond the worker:
+
+* **A tile cache.** A 30 s window starting on a 5 s grid decomposes into
+  exactly three 10 s tiles that also lie on that grid, so the whole snippet
+  sweep reuses the tiles the full-track vector already paid for. A 3-minute
+  track costs ~37 tile embeddings for the full track *and* ~31 windows,
+  instead of ~130. Same numbers, a third of the CPU — which is what makes
+  this affordable on a free CPU Space.
+* **The text tower.** `get_text_embedding` rides in the same checkpoint, so
+  descriptor tags are scored in the same 512-dim space as the audio, with no
+  extra model.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+CLAP_SR = 48_000              # CLAP is trained at 48 kHz
+CLAP_WINDOW = CLAP_SR * 10    # laion-clap's fixed input length (non-fusion)
+GRID_S = 5                    # snippet hop; also the tile-cache grid
+DIM = 512
+CKPT_ID = "default-630k"
+
+
+def l2(v: np.ndarray) -> np.ndarray:
+    n = float(np.linalg.norm(v))
+    return v / n if n > 1e-12 else v
+
+
+def load_audio(path: str) -> np.ndarray:
+    import librosa
+
+    audio, _ = librosa.load(path, sr=CLAP_SR, mono=True)
+    if audio.size == 0:
+        raise ValueError("empty audio")
+    return audio
+
+
+class Embedder:
+    """One loaded CLAP model. Holds the tile cache for the current track."""
+
+    ckpt = CKPT_ID
+
+    def __init__(self):
+        import laion_clap
+
+        # HTSAT-tiny is the arch of the auto-downloaded 630k-audioset
+        # checkpoint. $LAION_CLAP_MUSIC_CKPT is NOT honoured here: that
+        # variable switches to the HTSAT-base music checkpoint, a different
+        # vector space, and would silently invalidate every score.
+        self._model = laion_clap.CLAP_Module(enable_fusion=False,
+                                             amodel="HTSAT-tiny")
+        self._model.load_ckpt(ckpt=_local_ckpt())
+        try:
+            self._model.model.eval()   # no dropout — reproducibility
+        except Exception:
+            pass
+        self._cache: dict[tuple[int, int], np.ndarray] = {}
+
+    # -- raw calls ---------------------------------------------------------
+    def _raw(self, audio: np.ndarray) -> np.ndarray:
+        x = np.ascontiguousarray(audio[None, :], dtype=np.float32)
+        emb = self._model.get_audio_embedding_from_data(x=x, use_tensor=False)[0]
+        return np.asarray(emb, dtype=np.float32)
+
+    def _tile(self, audio: np.ndarray, s: int, e: int) -> np.ndarray:
+        key = (s, e - s)
+        hit = self._cache.get(key)
+        if hit is not None:
+            return hit
+        w = audio[s:e]
+        if len(w) < CLAP_WINDOW:          # pad the last kept tile, as the worker does
+            w = np.pad(w, (0, CLAP_WINDOW - len(w)))
+        out = self._tile_uncached(w)
+        self._cache[key] = out
+        return out
+
+    def _tile_uncached(self, w: np.ndarray) -> np.ndarray:
+        return self._raw(w)
+
+    # -- clap_worker._embed, over an arbitrary span ------------------------
+    def embed_span(self, audio: np.ndarray, lo: int, hi: int) -> np.ndarray:
+        """L2-normed vector for audio[lo:hi], identical to what clap_worker
+        would return for that span written out as its own file."""
+        W = CLAP_WINDOW
+        n = hi - lo
+        if n <= 0:
+            raise ValueError("empty span")
+        if n <= W:
+            # Short input is never randomly truncated → embed as-is,
+            # unpadded, exactly as the worker does.
+            return l2(self._raw(audio[lo:hi]))
+        tiles = []
+        for s in range(lo, hi, W):
+            e = min(s + W, hi)
+            if e - s < W // 2:            # drop a remainder under half a window
+                break
+            tiles.append(self._tile(audio, s, e))
+        return l2(np.mean(tiles, axis=0).astype(np.float32))
+
+    def embed_track(self, audio: np.ndarray) -> np.ndarray:
+        return self.embed_span(audio, 0, len(audio))
+
+    def embed_windows(self, audio: np.ndarray, window_s: float = 30.0,
+                      hop_s: float = GRID_S):
+        """-> (starts_seconds, matrix). Only windows that fit entirely inside
+        the track are emitted: a short tail window would be embedded under
+        different padding rules than the corpus, and a snippet you cannot
+        actually deliver is not a recommendation. A track shorter than the
+        window yields none at all — claiming a 0:00-0:30 clip of a
+        20-second file would be a straightforwardly false recommendation."""
+        n = len(audio)
+        win = int(round(window_s * CLAP_SR))
+        hop = int(round(hop_s * CLAP_SR))
+        if n < win:
+            return [], np.zeros((0, DIM), dtype=np.float32)
+        starts = list(range(0, n - win + 1, hop))
+        vecs = [self.embed_span(audio, s, s + win) for s in starts]
+        return [s / CLAP_SR for s in starts], np.asarray(vecs, dtype=np.float32)
+
+    def reset_cache(self) -> None:
+        self._cache.clear()
+
+    # -- text tower --------------------------------------------------------
+    def embed_texts(self, texts: list[str]) -> np.ndarray:
+        vecs = self._model.get_text_embedding(texts, use_tensor=False)
+        arr = np.asarray(vecs, dtype=np.float32)
+        return np.stack([l2(v) for v in arr])
+
+
+def _local_ckpt():
+    """Fetch 630k-audioset-best.pt from the Hub once and cache it.
+
+    laion_clap's own `load_ckpt()` wgets into its site-packages directory,
+    which a Space container discards on every rebuild. hf_hub_download puts
+    it in HF_HOME instead, where it survives restarts. Returns None (i.e.
+    let laion_clap do its default download) if the Hub is unreachable, so a
+    local run without network still works off an already-downloaded copy.
+    """
+    try:
+        from huggingface_hub import hf_hub_download
+
+        return hf_hub_download("lukewys/laion_clap", "630k-audioset-best.pt")
+    except Exception:
+        return None

livematch.py

@@ -0,0 +1,198 @@
+"""Corpus matching without a database — the offline half of the live matcher.
+
+`trackmap.rank_against_regions` does this against Postgres + pgvector. The
+hosted Space has no Postgres, only the weekly export (`liveexport.py`): an
+embedding matrix plus per-region index lists. This module runs the *same*
+maths on that export, so the Space and the CLI answer identically.
+
+Deliberately dependency-light — numpy only, and **no imports from the
+`marathon` package**. `cli deploy-live` copies this file verbatim into the
+Space repo, where it sits flat next to `app.py` and is imported as
+`livematch`. Anything it imports from a sibling module would break there.
+
+Thresholds are duplicated from `exploit.py` rather than imported (that module
+pulls in psycopg). `tests/test_livematch.py` asserts the two never drift.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+# Keep in lockstep with exploit.PLACE_THRESHOLD / DERIVE_THRESHOLD.
+# First-pass, calibrated on US/global trend data — see exploit.py's docstring.
+PLACE_THRESHOLD = 0.93
+DERIVE_THRESHOLD = 0.78
+
+
+def band(sim: float) -> str:
+    if sim >= PLACE_THRESHOLD:
+        return "place"
+    if sim >= DERIVE_THRESHOLD:
+        return "derive"
+    return "pass"
+
+
+class Corpus:
+    """The exported week: `emb` (N x 512, L2-normed float32), `sounds`
+    (index-aligned metadata) and `regions` (ISO2 -> pool/matched/idx/ranks).
+
+    Cosine is a plain dot product because every stored vector is L2-normed —
+    the same invariant `embed.py` maintains for the database.
+    """
+
+    def __init__(self, emb: np.ndarray, meta: dict):
+        self.emb = np.ascontiguousarray(emb, dtype=np.float32)
+        self.meta = meta
+        self.sounds = meta["sounds"]
+        self.regions = meta["regions"]
+        self.week = meta.get("week")
+        self.ckpt = meta.get("ckpt")
+        if self.emb.shape[0] != len(self.sounds):
+            raise ValueError(
+                f"corpus mismatch: {self.emb.shape[0]} vectors, "
+                f"{len(self.sounds)} metadata rows")
+
+    @classmethod
+    def load(cls, directory: str | Path) -> "Corpus":
+        d = Path(directory)
+        with np.load(d / "corpus.npz") as z:
+            emb = z["emb"]
+        meta = json.loads((d / "corpus.json").read_text())
+        return cls(emb, meta)
+
+    def sims(self, vec) -> np.ndarray:
+        """Cosine of one query vector against every sound. The query is
+        re-normalised defensively: an un-normed vector silently rescales
+        every score, which is the failure mode that makes a whole run wrong
+        without erroring."""
+        v = np.asarray(vec, dtype=np.float32).ravel()
+        if v.shape[0] != self.emb.shape[1]:
+            raise ValueError(
+                f"query is {v.shape[0]}-dim, corpus is {self.emb.shape[1]}-dim")
+        n = float(np.linalg.norm(v))
+        if n <= 1e-12:
+            raise ValueError("zero vector cannot be compared")
+        return self.emb @ (v / n)
+
+
+def rank_regions(corpus: Corpus, vec, top: int = 5) -> dict:
+    """-> {week, regions: {ISO2: {name, pool, matched, best, top: [...]}}}.
+
+    Mirrors `trackmap.rank_against_regions`, including its honesty
+    denominators: `pool` is how many distinct sounds chart in that country
+    this cycle, `matched` how many of those carry an embedding. A 95% best
+    score over 4 of 20 sounds is a different claim than over 20 of 20.
+    """
+    sims = corpus.sims(vec)
+    out = {}
+    for iso, r in corpus.regions.items():
+        idx = np.asarray(r["idx"], dtype=np.int64)
+        if idx.size == 0:
+            continue
+        local = sims[idx]
+        order = np.argsort(-local)[:top]
+        ranks = r.get("ranks") or [None] * len(r["idx"])
+        rows = []
+        for o in order:
+            s = corpus.sounds[int(idx[o])]
+            rows.append({
+                "artist": s["artist"], "title": s["title"],
+                "similarity": round(float(local[o]), 4),
+                "rank": ranks[int(o)],
+                "deezer_id": s.get("deezer_id"),
+                "source": s.get("source"), "chart": s.get("chart"),
+            })
+        out[iso] = {
+            "name": r.get("name", iso),
+            "pool": r["pool"], "matched": r["matched"],
+            "best": round(float(local[order[0]]), 4),
+            "top": rows,
+        }
+    return {"week": corpus.week, "regions": out}
+
+
+def pool_index(corpus: Corpus, isos: list[str]) -> np.ndarray:
+    """Union of the sound indices charting in any of `isos`."""
+    seen: set[int] = set()
+    for iso in isos:
+        r = corpus.regions.get(iso)
+        if r:
+            seen.update(int(i) for i in r["idx"])
+    return np.asarray(sorted(seen), dtype=np.int64)
+
+
+# --- snippet windows -------------------------------------------------------
+#
+# A distributor asks for ONE 30-second official clip per track. Two things
+# make a window a good answer, and they are not the same thing:
+#
+#   affinity  — how close that 30 seconds sits to the trend pool the track
+#               already fits best. Measured, and the reason to prefer one
+#               window over another at all.
+#   boundary  — whether it starts somewhere musical (on a downbeat, inside
+#               the repeating, high-energy part of the record) rather than
+#               mid-phrase. Derived from audio-brief's cutpoints signals.
+#
+# The blend weights below are HAND-SET AND UNFIT, exactly as cutpoints' own
+# weights are, and the UI says so.
+#
+# Affinities across one track's windows sit in a narrow band — measured on a
+# real master, 35 windows spanned 0.943 to 0.954. Min-max normalising that
+# range was the first attempt and it is wrong: it stretches an 0.001
+# difference, which is noise, into a decisive one, so a window starting
+# mid-phrase beats a downbeat-aligned window for no real reason. Instead the
+# gap to the best window is measured against a FIXED span. 0.03 is a fifth of
+# the 0.15-wide derive→place band, i.e. roughly the smallest similarity
+# difference worth overriding musical sense for; anything further behind than
+# that scores zero on affinity and has to win on boundary alone.
+AFFINITY_SPAN = 0.03
+W_AFFINITY, W_BOUNDARY = 0.70, 0.30
+
+
+def rank_windows(
+    affinity: list[float],
+    boundary: list[float],
+    starts: list[float],
+    top: int = 4,
+    min_gap_s: float = 15.0,
+    w_affinity: float = W_AFFINITY,
+    w_boundary: float = W_BOUNDARY,
+    span: float = AFFINITY_SPAN,
+) -> list[dict]:
+    """Rank 30s window candidates, keeping the picks distinct.
+
+    Greedy: take the best combined score, then suppress everything starting
+    within `min_gap_s` of it, repeat. Five near-identical windows around one
+    peak is not a shortlist.
+    """
+    if not affinity:
+        return []
+    a = np.asarray(affinity, dtype=np.float64)
+    b = np.asarray(boundary, dtype=np.float64)
+    a_norm = np.clip(1.0 - (float(a.max()) - a) / max(span, 1e-9), 0.0, 1.0)
+    combined = w_affinity * a_norm + w_boundary * b
+    order = np.argsort(-combined)
+    picked: list[dict] = []
+    for i in order:
+        s = float(starts[i])
+        if any(abs(s - p["start_s"]) < min_gap_s for p in picked):
+            continue
+        picked.append({
+            "start_s": round(s, 2),
+            "affinity": round(float(a[i]), 4),
+            "affinity_rel": round(float(a_norm[i]), 3),
+            "boundary": round(float(b[i]), 3),
+            "score": round(float(combined[i]), 3),
+            "band": band(float(a[i])),
+        })
+        if len(picked) >= top:
+            break
+    return picked
+
+
+def fmt_time(t: float) -> str:
+    t = max(0.0, float(t))
+    return f"{int(t // 60)}:{int(round(t % 60)):02d}"

packages.txt

@@ -0,0 +1 @@
+ffmpeg

render.py

@@ -0,0 +1,283 @@
+"""Analysis dict → one mobile-first HTML block.
+
+Same visual language and the same honesty labels as the weekly drop sheet
+(`marathon/static/signals.html`) and the trend map (`trackmap.render_map`):
+green = place, orange = derive, grey = pass, verdict cutoffs always carried
+next to the chip, denominators always shown.
+
+Deezer previews are resolved server-side into plain <audio src> tags. The
+drop sheet resolves them client-side via JSONP, but scripts injected into a
+Gradio HTML component do not run, and the preview URLs Deezer returns expire
+within about a day — which is fine here, because the person listening is the
+person who just pressed the button.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+import livematch
+
+ESC = html.escape
+
+
+def deezer_previews(ids: list[int], timeout: float = 6.0) -> dict[int, str]:
+    ids = [i for i in dict.fromkeys(ids) if i]
+    if not ids:
+        return {}
+
+    def one(tid):
+        try:
+            with urllib.request.urlopen(
+                    f"https://api.deezer.com/track/{tid}", timeout=timeout) as r:
+                return tid, (json.load(r) or {}).get("preview") or None
+        except Exception:
+            return tid, None
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        return {t: u for t, u in pool.map(one, ids) if u}
+
+
+CSS = """
+<style>
+.ml { --bg:#fbfbf9; --card:#fff; --ink:#141417; --muted:#55534e;
+  --line:#e5e3dc; --place:#0e9f6e; --derive:#f2610d; --pass:#8d8a82;
+  font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif;
+  color:var(--ink); max-width:760px; margin:0 auto; }
+.ml * { box-sizing:border-box; }
+.ml h2 { font-size:13px; letter-spacing:.14em; text-transform:uppercase;
+  color:#97948c; margin:26px 0 10px; font-weight:700; }
+.ml .hdr { font-size:20px; font-weight:700; margin:0 0 2px; letter-spacing:-.01em; }
+.ml .sub { color:var(--muted); font-size:13px; margin-bottom:6px; }
+.ml .card { background:var(--card); border:1px solid var(--line);
+  border-radius:14px; padding:13px 14px; margin-bottom:9px; }
+.ml .mkt { display:flex; align-items:center; gap:8px; font-weight:650; font-size:15px; }
+.ml .best { margin-left:auto; font-variant-numeric:tabular-nums; font-weight:700; }
+.ml .chip { font-size:10.5px; font-weight:800; letter-spacing:.08em;
+  padding:2px 7px; border-radius:999px; color:#fff; }
+.ml .chip.place { background:var(--place); } .ml .chip.derive { background:var(--derive); }
+.ml .chip.pass { background:var(--pass); }
+.ml .den { color:var(--muted); font-size:11.5px; margin:3px 0 8px; }
+.ml .row { display:flex; align-items:center; gap:8px; padding:4px 0;
+  font-size:13px; border-top:1px solid var(--line); }
+.ml .row:first-of-type { border-top:0; }
+.ml .pct { width:38px; font-variant-numeric:tabular-nums; color:var(--muted); flex:none; }
+.ml .lbl { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.ml .rk { color:var(--muted); font-size:11.5px; flex:none; }
+.ml audio { height:30px; max-width:150px; flex:none; }
+.ml .snip { display:flex; align-items:baseline; gap:9px; flex-wrap:wrap; }
+.ml .time { font-size:17px; font-weight:700; font-variant-numeric:tabular-nums; }
+.ml .why { color:var(--muted); font-size:12.5px; margin-top:6px; }
+.ml .tags { display:flex; flex-wrap:wrap; gap:6px; margin:4px 0 2px; }
+.ml .tag { border:1px solid var(--line); border-radius:999px; padding:3px 9px;
+  font-size:12.5px; background:#f6f5f1; }
+.ml .tag b { font-weight:650; } .ml .tag i { font-style:normal; color:var(--muted);
+  font-variant-numeric:tabular-nums; font-size:11px; margin-left:5px; }
+.ml .copy { width:100%; font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;
+  border:1px solid var(--line); border-radius:10px; padding:9px 10px;
+  background:#f6f5f1; color:var(--ink); resize:vertical; }
+.ml .note { color:var(--muted); font-size:12.5px; margin-top:8px; }
+.ml .caveats { border-top:1px solid var(--line); margin-top:24px; padding-top:12px;
+  color:var(--muted); font-size:12.5px; }
+.ml .caveats li { margin-bottom:5px; }
+.ml .foot { color:#97948c; font-size:11.5px; margin-top:14px; }
+/* On a phone the native audio control eats ~150px, which truncated every
+   record to "Diamond Pla…". Give the title the full width and drop the
+   player onto its own line. */
+@media (max-width: 560px) {
+  .ml .row { flex-wrap:wrap; padding:7px 0; }
+  .ml .lbl { white-space:normal; overflow:visible; }
+  .ml audio { flex:1 0 100%; max-width:100%; margin-top:5px; }
+}
+@media (prefers-color-scheme: dark) {
+  .ml { --bg:#161615; --card:#1d1d1b; --ink:#f5f4f0; --muted:#b0ada4;
+        --line:#333230; --pass:#7c7a73; }
+  .ml .tag, .ml .copy { background:#232321; }
+  .ml h2 { color:#8a877f; }
+}
+</style>
+"""
+
+
+def _pool_line(r: dict) -> str:
+    return (f'{r["matched"]} of {r["pool"]} sounds charting there this cycle '
+            f'were compared')
+
+
+def render(res: dict, track_label: str) -> str:
+    regions = res["regions"]
+    ids = [m.get("deezer_id")
+           for iso in res["shown_markets"]
+           for m in regions[iso]["top"][:3]]
+    ids += [p["nearest"]["deezer_id"] for p in res["snippets"]
+            if p.get("nearest") and p["nearest"].get("deezer_id")]
+    previews = deezer_previews(ids)
+
+    out = [CSS, '<div class="ml">']
+    out.append(f'<div class="hdr">{ESC(track_label)}</div>')
+    c = res["corpus"]
+    out.append(
+        f'<div class="sub">{res["duration_s"]:.0f}s · compared against '
+        f'{c["sounds"]:,} charting sounds in {c["regions"]} markets · '
+        f'chart week {ESC(str(res["week"]))}</div>')
+
+    # -- markets ----------------------------------------------------------
+    out.append('<h2>Where it fits</h2>')
+    for iso in res["shown_markets"]:
+        r = regions[iso]
+        b = livematch.band(r["best"])
+        out.append('<div class="card">')
+        out.append(
+            f'<div class="mkt"><span>{ESC(r["name"])} <span class="rk">{ESC(iso)}</span></span>'
+            f'<span class="chip {b}">{b.upper()}</span>'
+            f'<span class="best">{r["best"]*100:.0f}%</span></div>')
+        out.append(f'<div class="den">{_pool_line(r)}</div>')
+        for m in r["top"][:3]:
+            url = previews.get(m.get("deezer_id"))
+            player = (f'<audio controls preload="none" src="{ESC(url)}"></audio>'
+                      if url else '')
+            rank = f'#{m["rank"]}' if m.get("rank") else ''
+            out.append(
+                f'<div class="row"><span class="pct">{m["similarity"]*100:.0f}%</span>'
+                f'<span class="lbl">{ESC(m["artist"] or "—")} — {ESC(m["title"] or "—")}</span>'
+                f'<span class="rk">{ESC(rank)}</span>{player}</div>')
+        out.append('</div>')
+
+    # -- snippets ---------------------------------------------------------
+    out.append('<h2>Snippet recommendations · 30 seconds</h2>')
+    if not res["snippets"]:
+        out.append(
+            f'<div class="card">This file is {res["duration_s"]:.0f} seconds '
+            f'long — shorter than the 30-second clip a distributor asks for, '
+            f'so there is no window to choose. The market ranking above used '
+            f'the whole file.</div>')
+    for i, p in enumerate(res["snippets"], 1):
+        t0, t1 = livematch.fmt_time(p["start_s"]), livematch.fmt_time(p["end_s"])
+        mk = f'{ESC(p["market_name"])} ({ESC(p["market"])})' if p["market"] else '—'
+        out.append('<div class="card"><div class="snip">'
+                   f'<span class="rk">{i}</span>'
+                   f'<span class="time">{t0}–{t1}</span>'
+                   f'<span class="chip {p["band"]}">{p["band"].upper()}</span>'
+                   f'<span class="best">{p["affinity"]*100:.0f}%</span></div>')
+        near = p.get("nearest")
+        near_s = (f' Closest charting sound in that window: '
+                  f'{ESC(near["artist"] or "—")} — {ESC(near["title"] or "—")}.'
+                  if near else '')
+        dbeat = ''
+        if p.get("nearest_downbeat") is not None:
+            # Windows land on a 5-second grid, so the nearest downbeat is
+            # usually a fraction of a second away — quote the offset, not a
+            # rounded clock time that reads as the start you already have.
+            delta = p["nearest_downbeat"] - p["start_s"]
+            if abs(delta) < 0.06:
+                dbeat = ' Starts on the downbeat.'
+            else:
+                dbeat = (f' Nudge the start {abs(delta):.2f}s '
+                         f'{"later" if delta > 0 else "earlier"} '
+                         f'(to {p["nearest_downbeat"]:.2f}s) to land on the bar.')
+        out.append(
+            f'<div class="why">Closest to the {mk} trend pool at '
+            f'{p["affinity"]*100:.0f}%.{near_s}{dbeat}</div></div>')
+    if res["snippets"]:
+        out.append(
+            f'<div class="note">{res["window_count"]} windows were scanned at a '
+            f'5-second hop. Ranking blends how close a window sits to the trend '
+            f'pools above (70%) with a musical-boundary score — downbeat '
+            f'alignment plus how repeating and energetic that part of the record '
+            f'is (30%). Those weights are hand-set and unfitted. The vocal-stem '
+            f'signal audio-brief\'s cutpoints uses is not computed here.</div>')
+
+    # -- tags -------------------------------------------------------------
+    out.append('<h2>Suggested tags</h2>')
+    t = res["tags"]
+    if t.get("model"):
+        out.append('<div class="card"><div class="den">Model-suggested — CLAP '
+                   'zero-shot on the audio. Ordering is the signal; the numbers '
+                   'are cosine similarities, not probabilities. Check these '
+                   'before pasting: the model separates broad families well '
+                   '(an Afrobeats record sits far from techno or ambient) but '
+                   'is unreliable at naming a specific genre — on our own test '
+                   'records it ranked "latin pop" alongside afrobeats, and '
+                   'missed gospel entirely on a gospel track.</div>')
+        for group in ("genre", "mood", "production"):
+            rows = t["model"]["by_group"].get(group) or []
+            if not rows:
+                continue
+            chips = "".join(
+                f'<span class="tag"><b>{ESC(r["tag"])}</b><i>{r["score"]:.2f}</i></span>'
+                for r in rows)
+            out.append(f'<div class="den" style="margin-bottom:2px">{group}</div>'
+                       f'<div class="tags">{chips}</div>')
+        out.append('</div>')
+    else:
+        out.append('<div class="card"><div class="den">Model-suggested tags are '
+                   'switched off — the zero-shot text tower did not separate the '
+                   'vocabulary well enough on the reference check to be worth '
+                   'pasting into metadata.</div></div>')
+
+    tr = t["trend"]
+    out.append('<div class="card"><div class="den">Trend-derived — read off '
+               'this week\'s corpus, not guessed from the audio.</div>')
+    chips = "".join(
+        f'<span class="tag"><b>{ESC(m["iso"])}</b><i>{m["best"]*100:.0f}%</i></span>'
+        for m in tr["markets"][:8])
+    out.append(f'<div class="den" style="margin-bottom:2px">markets it sits '
+               f'nearest</div><div class="tags">{chips}</div>')
+    if tr["surfaces"]:
+        out.append('<div class="den" style="margin-bottom:2px">chart surfaces '
+                   'the nearest sounds trend on</div><div class="tags">'
+                   + "".join(f'<span class="tag">{ESC(s)}</span>'
+                             for s in tr["surfaces"]) + '</div>')
+    if tr["genres"]:
+        out.append('<div class="den" style="margin-bottom:2px">genre slugs from '
+                   'the charts</div><div class="tags">'
+                   + "".join(f'<span class="tag">{ESC(g)}</span>'
+                             for g in tr["genres"]) + '</div>')
+    else:
+        out.append(f'<div class="note">No genre tag is derived from the charts: '
+                   f'{c["genre_labelled"]} of {c["sounds"]:,} sounds in this '
+                   f'week\'s corpus carry a genre slug — the YouTube country '
+                   f'charts publish none.</div>')
+    out.append('</div>')
+
+    out.append('<div class="card"><div class="den">Copy line for the metadata '
+               'form</div>'
+               f'<textarea class="copy" rows="3" readonly>{ESC(t["copy_line"])}'
+               '</textarea></div>')
+
+    # -- caveats ----------------------------------------------------------
+    tempo = res["beat"].get("tempo")
+    out.append(
+        '<div class="caveats"><b>Read this with the numbers.</b><ul>'
+        '<li><b>Similarity is not a hit prediction.</b> It measures how close '
+        'two recordings sound in texture. It says nothing about whether a '
+        'record will perform.</li>'
+        f'<li><b>Cutoffs are first-pass and US-calibrated.</b> Over '
+        f'{livematch.PLACE_THRESHOLD:.0%} reads as a direct fit, '
+        f'{livematch.DERIVE_THRESHOLD:.0%}–{livematch.PLACE_THRESHOLD:.0%} as '
+        f'remix or edit territory, below that as no adjacency. They were fitted '
+        f'on US and global trend data and have not been re-fitted for African '
+        f'markets.</li>'
+        '<li><b>One week of charts.</b> A single snapshot cannot tell a rising '
+        'sound from a fading one, so there are no trend arrows here.</li>'
+        '<li><b>Chart sounds are 30-second previews; your upload is the full '
+        'master.</b> A full-length vector averages over more of the record and '
+        'scores higher against everything, so read the ordering rather than '
+        'comparing one track\'s absolute numbers with another\'s.</li>'
+        '<li><b>The model hears texture only</b> — not lyrics, language, who is '
+        'on the record, or whether a market would accept it.</li>'
+        + (f'<li><b>Tempo read as {tempo:.0f} BPM</b> with an Afrobeats-leaning '
+           f'110 BPM prior; a wrong read only shifts the downbeat suggestions, '
+           f'not the market ranking.</li>' if tempo else
+           '<li><b>The beat tracker could not read this file</b>, so snippet '
+           'ranking used trend affinity alone.</li>')
+        + '</ul></div>')
+    out.append(
+        f'<div class="foot">corpus: {ESC(str(c["week"]))} · {c["sounds"]:,} sounds · '
+        f'{c["regions"]} markets · sources: {ESC(", ".join(c["sources"]) or "—")} · '
+        f'exported {ESC(str(c["generated_at"]))}</div>')
+    out.append('</div>')
+    return "".join(out)

requirements.txt

@@ -0,0 +1,18 @@
+# Marathon live matcher — Space runtime.
+#
+# The pins that matter, learned from audio-brief's own build:
+#   * laion-clap imports torchvision at runtime but does NOT declare it, so
+#     it must be listed explicitly or the first embed fails at call time.
+#   * laion-clap constrains numpy<2 (resolves to 1.26.x). librosa is fine
+#     with that; pinning it here makes the resolution explicit rather than
+#     a surprise from a transitive constraint.
+# The checkpoint itself is not vendored — clap_embed pulls
+# lukewys/laion_clap:630k-audioset-best.pt into HF_HOME on first use.
+
+gradio==6.19.0
+laion-clap
+torchvision
+librosa>=0.10.1
+soundfile>=0.12
+numpy>=1.24,<2
+huggingface_hub

tags.py

@@ -0,0 +1,176 @@
+"""Suggested tags for distributor metadata forms.
+
+Two groups, kept visually and factually apart because they are different
+kinds of claim:
+
+  model-suggested — CLAP zero-shot. The checkpoint's text tower embeds a
+      curated vocabulary once at startup; the uploaded track's audio vector is
+      scored against it by cosine, in the same 512-dim space. This is the
+      model's opinion about texture. It has no idea what language the vocal is
+      in, who is on the record, or what a market calls the style.
+
+  trend-derived — read straight off the corpus: which markets the track's
+      nearest charting neighbours are trending in, on which chart surfaces,
+      and their genre slugs where the source publishes any. Grounded in this
+      week's data, with the same limits as the rest of the scan.
+
+CLAP audio↔text cosines sit in a narrow band (roughly 0.15–0.45) and are NOT
+probabilities. The ordering is the signal; the number is shown so the gap
+between #1 and #10 is visible, not so anyone reads 0.31 as 31% confidence.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# CLAP's text tower was trained on captions, so a sentence beats a bare word,
+# and the sentence itself moves the answer more than is comfortable. Four
+# templates were scored against known-genre probes from the corpus
+# (2026-08-21, checkpoint default-630k, genre vocabulary only, top-6 shown):
+#
+#   "a {} song"                  YO YO → afrobeats .52 FIRST; Davido "Guide"
+#                                → afrobeats tied first .53; KATSEYE → pop,
+#                                k-pop 2nd
+#   "This is a {} music track."  YO YO → latin pop .474 first, afrobeats 4th;
+#                                Davido → latin pop first
+#   "This audio is {} music."    YO YO → afrobeats first; Davido → afrobeats
+#                                first; but gospel probe → indie pop, pop
+#   "{}"                         worst everywhere; reggae and bollywood
+#                                surface on Afrobeats records
+#
+# "a {} song" wins on the probes and is what ships. The measurement that
+# matters more is what it did NOT fix: on Bad Bunny the top tag is "afro
+# house", and on a live gospel record "gospel" and "worship" appear nowhere
+# in the top six under any template. Family-level separation is real
+# (afro-family vs techno/ambient clears by ~0.09 cosine); specific genre
+# naming is not reliable, and the UI says so rather than implying otherwise.
+TEMPLATE = "a {} song"
+
+VOCAB: dict[str, list[str]] = {
+    "genre": [
+        "afrobeats", "afro pop", "afro house", "amapiano", "afro swing",
+        "gengetone", "bongo flava", "genge", "kwaito", "gqom", "azonto",
+        "highlife", "afro fusion", "afro soul", "dancehall", "reggae",
+        "soca", "kompa", "coupé-décalé", "reggaeton", "latin pop",
+        "hip hop", "trap", "drill", "uk drill", "grime", "r&b",
+        "contemporary r&b", "pop", "dance pop", "house", "deep house",
+        "tech house", "techno", "electro", "drum and bass", "jungle",
+        "dubstep", "garage", "uk funky", "gospel", "worship", "soul",
+        "funk", "jazz", "rock", "indie pop", "country", "k-pop",
+        "bollywood", "arabic pop", "lo-fi hip hop", "ambient",
+    ],
+    "mood": [
+        "uplifting", "euphoric", "energetic", "confident", "playful",
+        "romantic", "sensual", "melancholic", "sad", "nostalgic",
+        "laid-back", "hypnotic", "dark", "aggressive", "triumphant",
+        "spiritual", "carefree", "moody", "dreamy", "tense",
+    ],
+    "production": [
+        "vocal-led", "instrumental", "male vocal", "female vocal",
+        "group vocal", "call and response", "acoustic", "electronic",
+        "percussive", "log drum bassline", "808 bass", "guitar-led",
+        "piano-led", "synth-led", "horn section", "auto-tuned vocal",
+        "sparse arrangement", "dense arrangement", "live drums",
+        "programmed drums", "sped-up", "slowed and reverbed",
+        "lo-fi production", "polished production", "danceable",
+        "mid-tempo", "up-tempo", "down-tempo",
+    ],
+}
+
+# Groups whose members are mutually exclusive enough that a softmax-style
+# read would mislead; we never softmax, but we do cap how many of each group
+# reaches the copy line.
+TOP_PER_GROUP = {"genre": 4, "mood": 3, "production": 4}
+
+# Within a group, drop anything trailing the group's leader by more than this.
+# Measured reason: on YO YO the production group returned "danceable" at 0.34
+# and then "electronic" 0.15, "percussive" 0.15, "acoustic" 0.14 — a flat tail
+# that includes two contradictory tags. Filling a quota with a flat tail puts
+# noise into someone's metadata form. 0.10 is hand-set, like everything else
+# here; the effect is only ever to show fewer tags, never different ones.
+TAG_MARGIN = 0.10
+
+
+class TagVocab:
+    """Text-tower vectors for the vocabulary, embedded once."""
+
+    def __init__(self, embedder):
+        self.terms: list[tuple[str, str]] = [
+            (group, term) for group, terms in VOCAB.items() for term in terms]
+        prompts = [TEMPLATE.format(t) for _, t in self.terms]
+        self.vectors = embedder.embed_texts(prompts)   # (T, 512), L2-normed
+
+    def score(self, audio_vec) -> list[dict]:
+        v = np.asarray(audio_vec, dtype=np.float32).ravel()
+        n = float(np.linalg.norm(v))
+        if n <= 1e-12:
+            raise ValueError("zero vector cannot be scored")
+        sims = self.vectors @ (v / n)
+        out = [{"group": g, "tag": t, "score": round(float(s), 4)}
+               for (g, t), s in zip(self.terms, sims)]
+        out.sort(key=lambda r: -r["score"])
+        return out
+
+    def top(self, audio_vec, per_group: dict | None = None,
+            margin: float = TAG_MARGIN) -> dict:
+        per_group = per_group or TOP_PER_GROUP
+        ranked = self.score(audio_vec)
+        picked: dict[str, list[dict]] = {g: [] for g in VOCAB}
+        for r in ranked:
+            bucket = picked[r["group"]]
+            if len(bucket) >= per_group.get(r["group"], 3):
+                continue
+            if bucket and r["score"] < bucket[0]["score"] - margin:
+                continue          # flat tail — see TAG_MARGIN
+            bucket.append(r)
+        return {"by_group": picked, "ranked": ranked}
+
+
+def discrimination_check(vocab: TagVocab, audio_vec,
+                         expect_above: list[str],
+                         expect_below: list[str]) -> dict:
+    """Does the text tower actually separate anything on this vector?
+
+    Used by `cli verify-live` on a known Afrobeats reference: if the
+    afrobeats family does not outrank e.g. techno, zero-shot tagging is noise
+    on this checkpoint and the honest move is to ship group two only.
+    """
+    ranked = {r["tag"]: r["score"] for r in vocab.score(audio_vec)}
+    above = {t: ranked.get(t) for t in expect_above}
+    below = {t: ranked.get(t) for t in expect_below}
+    lo_above = min(v for v in above.values() if v is not None)
+    hi_below = max(v for v in below.values() if v is not None)
+    return {"above": above, "below": below,
+            "margin": round(lo_above - hi_below, 4),
+            "passed": lo_above > hi_below}
+
+
+def trend_tags(regions: dict, top_isos: list[str], corpus_sounds: list[dict],
+               neighbour_idx: list[int]) -> dict:
+    """Tags read off the corpus rather than guessed from audio."""
+    markets = [{"iso": iso, "name": regions[iso]["name"],
+                "best": regions[iso]["best"]}
+               for iso in top_isos if iso in regions]
+    surfaces, genres = [], []
+    for i in neighbour_idx:
+        s = corpus_sounds[i]
+        if s.get("chart") and s["chart"] not in surfaces:
+            surfaces.append(s["chart"])
+        for g in s.get("genres") or []:
+            if g not in genres:
+                genres.append(g)
+    return {"markets": markets, "surfaces": surfaces, "genres": genres}
+
+
+def copy_line(model_tags: dict, trend: dict) -> str:
+    """One comma-separated line, ready to paste into a metadata field."""
+    parts = [r["tag"] for g in ("genre", "mood", "production")
+             for r in model_tags["by_group"].get(g, [])]
+    parts += trend.get("genres") or []
+    parts += [m["iso"] for m in trend.get("markets", [])[:5]]
+    seen, out = set(), []
+    for p in parts:
+        if p not in seen:
+            seen.add(p)
+            out.append(p)
+    return ", ".join(out)

verify.py

@@ -0,0 +1,98 @@
+"""Prove the Space's embeddings match the corpus before anything ships.
+
+Run inside an environment that has laion_clap (audio-brief's venv locally,
+the Space's own env when run there), from a *staged* directory — i.e. the
+exact set of files that gets uploaded:
+
+    python verify.py --stage DIR --parity AUDIO --parity-ref VECTOR.npy \
+                     [--analyse AUDIO] [--out RESULT.json]
+
+`--parity` re-embeds a track whose vector is already in the corpus (the
+canonical path being audio-brief's clap_worker via WorkerBackend) and reports
+the cosine against the stored vector. Anything below 0.9999 means this code
+has drifted from the worker and every similarity the app shows would be
+quietly wrong.
+
+`--analyse` runs a full headless analysis so the market ranking, snippets and
+tags can be eyeballed without a browser.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+PARITY_FLOOR = 0.9999
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--stage", required=True)
+    ap.add_argument("--parity", default=None)
+    ap.add_argument("--parity-ref", default=None)
+    ap.add_argument("--analyse", default=None)
+    ap.add_argument("--out", default=None)
+    args = ap.parse_args()
+
+    sys.path.insert(0, str(Path(args.stage).resolve()))
+    import analysis  # noqa: E402
+    import clap_embed  # noqa: E402
+    import livematch  # noqa: E402
+    import tags as tagmod  # noqa: E402
+
+    corpus = livematch.Corpus.load(args.stage)
+    emb = clap_embed.Embedder()
+    result: dict = {"corpus": {"week": corpus.week, "ckpt": corpus.ckpt,
+                               "sounds": len(corpus.sounds),
+                               "regions": len(corpus.regions)}}
+
+    if args.parity:
+        v = emb.embed_track(clap_embed.load_audio(args.parity))
+        ref = np.load(args.parity_ref).astype(np.float32).ravel()
+        ref = ref / np.linalg.norm(ref)
+        cos = float(np.dot(v, ref))
+        result["parity"] = {"file": args.parity, "cosine": round(cos, 7),
+                            "floor": PARITY_FLOOR, "passed": cos >= PARITY_FLOOR}
+
+    vocab = tagmod.TagVocab(emb)
+    if args.analyse:
+        res = analysis.analyse_track(args.analyse, emb, corpus, vocab=vocab)
+        result["zero_shot_check"] = tagmod.discrimination_check(
+            vocab, res["track_vec"],
+            expect_above=["afrobeats", "afro pop", "afro fusion"],
+            expect_below=["techno", "country", "k-pop", "ambient"])
+        res.pop("track_vec", None)
+        result["analysis"] = {
+            "duration_s": res["duration_s"], "week": res["week"],
+            "beat": res["beat"], "window_count": res["window_count"],
+            "markets": [{"iso": i, "name": res["regions"][i]["name"],
+                         "best": res["regions"][i]["best"],
+                         "band": livematch.band(res["regions"][i]["best"]),
+                         "matched": res["regions"][i]["matched"],
+                         "pool": res["regions"][i]["pool"],
+                         "top": res["regions"][i]["top"][:3]}
+                        for i in res["shown_markets"]],
+            "snippets": res["snippets"],
+            "tags": {
+                "by_group": {g: rows for g, rows
+                             in (res["tags"]["model"]["by_group"].items()
+                                 if res["tags"]["model"] else [])},
+                "trend": res["tags"]["trend"],
+                "copy_line": res["tags"]["copy_line"],
+            },
+        }
+
+    text = json.dumps(result, indent=2, default=str)
+    if args.out:
+        Path(args.out).write_text(text)
+    print(text)
+    parity = result.get("parity")
+    return 0 if (parity is None or parity["passed"]) else 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())