feat(api): headless audio_to_prompt endpoint — audio in, SA3 prompt out

- new api_name="audio_to_prompt" route (hidden components + button, the
proven gradio_client pattern): file in -> deterministic SA3 prompt +
measured JSON out. No wallet, no LLM, no pollen — structural prompt
from outputs.sa3_variation_prompt
- fast=True skips demucs + basic-pitch (~2s vs ~30s); reuses analyze()'s
run_stems/run_midi flags
- same ingest as the UI upload: video containers + aac-family are
ffmpeg-extracted via _prepare_source_audio
- gated by Space secret AUDIO_BRIEF_API_TOKEN (constant-time compare);
open when unset
- returns {prompt, match_style_prompt, measured{...}, fast_mode,
stages_ok, errors}
- docs/API.md with gradio_client usage + gating setup

Verified locally end-to-end via gradio_client.handle_file: fast + full
(4-stem demucs) paths, token accept/reject, video extract, missing-file
error. Endpoint appears in view_api.

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

app.py

@@ -1966,6 +1966,101 @@ def send_tile_to_analysis(tile_id: str | None, session_id: str | None = ""):
     )
 
 
+# ── Headless API: audio → derived SA3 prompt ─────────────────────────────
+# Exposed via a hidden button with api_name="audio_to_prompt" (registered
+# in build_ui). Deliberately wallet-free: the returned prompt is the
+# DETERMINISTIC structural prompt (outputs.sa3_variation_prompt) built
+# from measurements alone — no Pollinations LLM call, no pollen cost, so
+# the endpoint works for any caller. LLM-polished prose stays a UI-only
+# feature (needs the per-session wallet).
+#
+# Gate: if the Space secret AUDIO_BRIEF_API_TOKEN is set, callers must
+# pass a matching `token`. Unset → open (fine for local/dev). This keeps
+# casual abuse of the CPU-heavy demucs stage out on the public Space.
+def _api_token_ok(token: str) -> bool:
+    import os
+    required = os.environ.get("AUDIO_BRIEF_API_TOKEN", "").strip()
+    if not required:
+        return True  # no gate configured — open endpoint
+    # Constant-time compare so the token can't be guessed byte-by-byte.
+    import hmac
+    return hmac.compare_digest(str(token or "").strip(), required)
+
+
+def audio_to_prompt_api(audio_path: str | None,
+                        token: str = "",
+                        fast: bool = False,
+                        bpm_prior: str = "default") -> dict:
+    """Headless endpoint: an audio (or video) file in → a ready-to-use SA3
+    prompt + the measured analysis JSON out. No wallet, no LLM.
+
+    Params (positional order for gradio_client.predict):
+      audio_path : uploaded file path (wav/mp3/flac/ogg + mp4/mov/m4a/… —
+                   video/aac are ffmpeg-extracted, same as the UI upload).
+      token      : shared secret; required only when AUDIO_BRIEF_API_TOKEN
+                   is set on the Space.
+      fast       : skip demucs stems + basic-pitch bass-MIDI (~2 s instead
+                   of ~30 s). Prompt omits stem/bassline detail.
+      bpm_prior  : genre slug or numeric string to seed the beat tracker
+                   (see BPM_PRIORS) — "default" is fine for most.
+
+    Returns a JSON-able dict:
+      { prompt, match_style_prompt, measured{…}, fast_mode, stages_ok, errors }
+    """
+    if not _api_token_ok(token):
+        raise gr.Error("invalid or missing API token")
+    if not audio_path:
+        raise gr.Error("no audio file provided")
+
+    # Same ingest path as the UI: video containers + aac-family → WAV.
+    src = _prepare_source_audio(audio_path)
+
+    a = analyze(
+        src,
+        bpm_prior=(bpm_prior or "default"),
+        run_stems=not fast,
+        run_midi=not fast,
+        run_tags=False,
+        run_embedding=False,
+    )
+
+    # Decode is the only stage whose failure makes the output meaningless
+    # (no BPM/key/anything). Surface that as an error rather than a prompt
+    # full of '?'. Individual heavy-stage failures (demucs/basic-pitch)
+    # are non-fatal — the structural prompt still stands on librosa data.
+    if a.bpm is None and a.errors:
+        raise gr.Error(f"analysis failed: {a.errors}")
+
+    return {
+        "prompt": outputs.sa3_variation_prompt(a),
+        "match_style_prompt": outputs.sa3_match_style_prompt(a),
+        "measured": {
+            "bpm": a.bpm,
+            "key": a.key,
+            "key_mode": a.key_mode,
+            "key_confidence": a.key_correlation,
+            "duration_s": a.duration_s,
+            "lufs_i": a.lufs_i,
+            "lufs_lra": a.lufs_lra,
+            "true_peak_db": a.true_peak_db,
+            "sections": a.sections,
+            "stems": sorted(a.stems) if a.stems else [],
+            "stem_stats": a.stem_stats or None,
+            "voiceover_present": a.voiceover_present,
+            "bass_midi": _bass_midi_summary(a),
+        },
+        "fast_mode": bool(fast),
+        "stages_ok": [k for k, v in {
+            "bpm_key": a.bpm is not None,
+            "sections": bool(a.sections),
+            "loudness": a.lufs_i is not None,
+            "stems": bool(a.stems),
+            "bass_midi": _bass_midi_summary(a) is not None,
+        }.items() if v],
+        "errors": a.errors or [],
+    }
+
+
 def build_ui() -> gr.Blocks:
     # Theme + CSS must live on the Blocks instance (not on .launch()) so
     # HF Spaces — which auto-launches `demo` without our launch args —
@@ -4798,6 +4893,37 @@ def build_ui() -> gr.Blocks:
             js=NOTEPAD_BOOTSTRAP_JS,
         )
 
+        # ── Headless API surface ─────────────────────────────────────────
+        # Hidden components + a hidden button carry the api_name route so
+        # gradio_client (and plain HTTP POST to /gradio_api/call/…) can
+        # reach audio_to_prompt_api. Visibility is UI-only — the endpoint
+        # is registered server-side regardless. This is the same pattern
+        # the app's other api_name routes use, and it plays nicely with
+        # gradio_client.handle_file for the upload.
+        with gr.Group(visible=False):
+            _api_audio_in = gr.File(
+                type="filepath",
+                file_types=[
+                    "audio",
+                    ".mp3", ".wav", ".flac", ".ogg", ".aiff", ".aif",
+                    ".m4a", ".aac", ".opus", ".wma",
+                    ".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi",
+                ],
+                label="api audio in",
+            )
+            _api_token_in = gr.Textbox(value="", label="api token")
+            _api_fast_in = gr.Checkbox(value=False, label="fast (skip demucs)")
+            _api_bpm_in = gr.Textbox(value="default", label="bpm prior")
+            _api_json_out = gr.JSON(label="api result")
+            _api_btn = gr.Button("audio_to_prompt")
+            _api_btn.click(
+                fn=audio_to_prompt_api,
+                inputs=[_api_audio_in, _api_token_in, _api_fast_in, _api_bpm_in],
+                outputs=[_api_json_out],
+                api_name="audio_to_prompt",
+                show_progress="hidden",
+            )
+
     return demo
 
 

docs/API.md

@@ -0,0 +1,76 @@
+# audio-brief API — audio in → SA3 prompt out
+
+The Space exposes a headless endpoint that runs the analysis pipeline and
+returns a ready-to-use SA3 prompt plus the measured JSON. **No wallet, no
+LLM** — the prompt is the deterministic structural prompt built from
+measurements alone.
+
+- **Endpoint:** `/audio_to_prompt`
+- **Base URL:** `https://kalamishere-audio-brief.hf.space/`
+- **Auth:** optional shared token (see *Gating* below).
+
+## Parameters (positional)
+
+| # | Name | Type | Default | Notes |
+|---|---|---|---|---|
+| 1 | `audio` | file | — | wav/mp3/flac/ogg + mp4/mov/m4a/webm/… (video & aac-family are ffmpeg-extracted) |
+| 2 | `token` | str | `""` | required only when the Space secret `AUDIO_BRIEF_API_TOKEN` is set |
+| 3 | `fast` | bool | `false` | skip demucs stems + bass-MIDI → ~2 s instead of ~30 s; prompt omits stem/bassline detail |
+| 4 | `bpm_prior` | str | `"default"` | genre slug or numeric string to seed the beat tracker |
+
+## Returns
+
+```json
+{
+  "prompt": "# SA3 variation prompt\nBPM: 128 (anchor)\nKey: A minor\n…",
+  "match_style_prompt": "…",
+  "measured": {
+    "bpm": 128.0, "key": "A", "key_mode": "minor", "key_confidence": 0.82,
+    "duration_s": 30.0, "lufs_i": -9.1, "lufs_lra": 4.2, "true_peak_db": -0.3,
+    "sections": [...], "stems": ["bass","drums","other","vocals"],
+    "stem_stats": {...}, "voiceover_present": false, "bass_midi": {...}
+  },
+  "fast_mode": false,
+  "stages_ok": ["bpm_key","sections","loudness","stems","bass_midi"],
+  "errors": []
+}
+```
+
+## Python (recommended)
+
+```python
+from gradio_client import Client, handle_file
+
+c = Client("kalamishere/audio-brief")   # or the full .hf.space URL
+r = c.predict(
+    handle_file("track.wav"),
+    "YOUR_TOKEN",     # "" if the Space isn't gated
+    True,             # fast=True
+    "default",
+    api_name="/audio_to_prompt",
+)
+print(r["prompt"])
+```
+
+## Gating (protect the CPU-heavy endpoint)
+
+The public Space runs demucs on every full call, so leave it gated. Set a
+Space secret in **Settings → Variables and secrets**:
+
+```
+AUDIO_BRIEF_API_TOKEN = <a long random string>
+```
+
+When set, calls must pass a matching `token` (constant-time compared) or
+get `invalid or missing API token`. When unset, the endpoint is open —
+fine for local runs.
+
+## Notes / limits
+
+- **Speed:** full analysis is demucs-bound (~30 s on HF free CPU). Use
+  `fast=true` for interactive/high-volume use, or upgrade the Space tier.
+- **Concurrency:** the queue caps concurrency at 4 (see `demo.queue`).
+  Heavy parallel traffic on the free tier will swap — see the low-RAM
+  ceiling note in the pipeline docs.
+- **YouTube isn't an API input** — pass a file. (The UI's YouTube box
+  yt-dlp's to a file first; that flow is UI-only.)