remixflow 0.1.0__tar.gz

remixflow-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/
+venv/
+
+# RemixFlow runtime data (imported songs + generated audio)
+remixflow_data/
+*_data/
+
+# Node / frontend
+node_modules/
+frontend/dist/
+
+# Built UI is generated by `npm run build` (shipped in the wheel, not committed)
+backend/remixflow/static/assets/
+backend/remixflow/static/index.html
+
+# OS / editor
+.DS_Store
+*.swp
+
+# Test audio
+*.mp3
+
+# Audio outputs (derived works / large binaries)
+*.wav
+samples/
+
+# TS build info
+frontend/tsconfig.tsbuildinfo

remixflow-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: remixflow
+Version: 0.1.0
+Summary: An AI-powered music evolution platform — generate endless familiar-but-fresh variations of a song.
+Project-URL: Homepage, https://github.com/fbobe321/remixflow
+Project-URL: Repository, https://github.com/fbobe321/remixflow
+Author: RemixFlow
+License: MIT
+Keywords: ai,audio,diffusion,generation,music,remix
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: soundfile>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: audio
+Requires-Dist: librosa>=0.10; extra == 'audio'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RemixFlow — backend
+
+FastAPI backend for the RemixFlow music-evolution platform. See the repo-root
+`README.md` for the full picture; this file covers the Python package.
+
+## Install
+
+```bash
+pip install -e ".[audio,dev]"   # audio extra adds librosa (tempo/pitch/key)
+```
+
+Core deps are pure PyPI wheels. The bundled libsndfile (via `soundfile`) reads
+**and writes** MP3/WAV/FLAC/OGG with no system packages — **no ffmpeg needed**.
+The `audio` extra pulls in `librosa` for tempo/key detection and
+time-stretch/pitch-shift.
+
+## Run
+
+```bash
+remixflow serve                 # http://127.0.0.1:8770  (API + built UI)
+remixflow serve --reload        # dev auto-reload
+```
+
+Interactive API docs at `/docs`.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `params.py` | Single source of truth for every steering control & identity lock (PRD §3, §4). Served to the UI via `/api/controls`. |
+| `models.py` | Pydantic schemas: `Song`, `Variant`, `Steering`, evolution `TreeNode`. |
+| `audio/io.py` | Load/save with graceful degradation (soundfile → librosa). |
+| `audio/analysis.py` | Feature extraction + Musical-DNA embedding + similarity. |
+| `generation/base.py` | The `Generator` contract every backend implements. |
+| `generation/dsp.py` | Reference DSP backend — real, audible variations today. |
+| `generation/registry.py` | Plug point for model backends (ACE-Step, Stable Audio, MusicGen). |
+| `service.py` | Orchestration: import → steer → generate → evaluate → branch. |
+| `store.py` | File-backed store (JSON + audio dir); swap for a DB later. |
+| `app.py` | FastAPI routes; serves the built React UI from `static/`. |
+
+## Adding a real model backend
+
+Implement `Generator` and register it:
+
+```python
+from remixflow.generation import Generator, register_generator
+
+class AceStepBackend(Generator):
+    name = "ace-step"
+    description = "ACE-Step 1.5 diffusion"
+    def generate(self, parent, steering, *, original=None, seed=None):
+        ...  # map steering -> latent edits, run the model, return GenerationResult
+
+register_generator(AceStepBackend())
+```
+
+It then appears in `/api/backends` and is selectable via `POST /api/generate?backend=ace-step`.
+
+## Config (env vars)
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `REMIXFLOW_DATA_DIR` | `./remixflow_data` | Where songs/variants/audio persist. |
+| `REMIXFLOW_MAX_UPLOAD_MB` | `50` | Upload size cap. |
+| `REMIXFLOW_CORS` | `*` | Comma-separated allowed origins. |

remixflow-0.1.0/README.md

@@ -0,0 +1,65 @@
+# RemixFlow — backend
+
+FastAPI backend for the RemixFlow music-evolution platform. See the repo-root
+`README.md` for the full picture; this file covers the Python package.
+
+## Install
+
+```bash
+pip install -e ".[audio,dev]"   # audio extra adds librosa (tempo/pitch/key)
+```
+
+Core deps are pure PyPI wheels. The bundled libsndfile (via `soundfile`) reads
+**and writes** MP3/WAV/FLAC/OGG with no system packages — **no ffmpeg needed**.
+The `audio` extra pulls in `librosa` for tempo/key detection and
+time-stretch/pitch-shift.
+
+## Run
+
+```bash
+remixflow serve                 # http://127.0.0.1:8770  (API + built UI)
+remixflow serve --reload        # dev auto-reload
+```
+
+Interactive API docs at `/docs`.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `params.py` | Single source of truth for every steering control & identity lock (PRD §3, §4). Served to the UI via `/api/controls`. |
+| `models.py` | Pydantic schemas: `Song`, `Variant`, `Steering`, evolution `TreeNode`. |
+| `audio/io.py` | Load/save with graceful degradation (soundfile → librosa). |
+| `audio/analysis.py` | Feature extraction + Musical-DNA embedding + similarity. |
+| `generation/base.py` | The `Generator` contract every backend implements. |
+| `generation/dsp.py` | Reference DSP backend — real, audible variations today. |
+| `generation/registry.py` | Plug point for model backends (ACE-Step, Stable Audio, MusicGen). |
+| `service.py` | Orchestration: import → steer → generate → evaluate → branch. |
+| `store.py` | File-backed store (JSON + audio dir); swap for a DB later. |
+| `app.py` | FastAPI routes; serves the built React UI from `static/`. |
+
+## Adding a real model backend
+
+Implement `Generator` and register it:
+
+```python
+from remixflow.generation import Generator, register_generator
+
+class AceStepBackend(Generator):
+    name = "ace-step"
+    description = "ACE-Step 1.5 diffusion"
+    def generate(self, parent, steering, *, original=None, seed=None):
+        ...  # map steering -> latent edits, run the model, return GenerationResult
+
+register_generator(AceStepBackend())
+```
+
+It then appears in `/api/backends` and is selectable via `POST /api/generate?backend=ace-step`.
+
+## Config (env vars)
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `REMIXFLOW_DATA_DIR` | `./remixflow_data` | Where songs/variants/audio persist. |
+| `REMIXFLOW_MAX_UPLOAD_MB` | `50` | Upload size cap. |
+| `REMIXFLOW_CORS` | `*` | Comma-separated allowed origins. |

remixflow-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remixflow"
+version = "0.1.0"
+description = "An AI-powered music evolution platform — generate endless familiar-but-fresh variations of a song."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "RemixFlow" }]
+keywords = ["music", "audio", "generation", "diffusion", "ai", "remix"]
+
+# Core deps — all pip-installable from PyPI, no system packages required to boot.
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "pydantic>=2.6",
+    "python-multipart>=0.0.9",
+    "numpy>=1.24",
+    "soundfile>=0.12",   # WAV/FLAC/OGG read/write via libsndfile (bundled wheels)
+]
+
+[project.optional-dependencies]
+# Richer analysis + time-stretch/pitch-shift. librosa reaches MP3 via ffmpeg.
+audio = ["librosa>=0.10"]
+dev = ["pytest>=8.0", "httpx>=0.27"]
+
+[project.scripts]
+remixflow = "remixflow.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/fbobe321/remixflow"
+Repository = "https://github.com/fbobe321/remixflow"
+
+# The built React UI is emitted into remixflow/static (see frontend build) and is
+# .gitignored (build output). `artifacts` forces it into the sdist/wheel anyway,
+# so `pip install remixflow` serves the app with no Node.
+[tool.hatch.build]
+artifacts = ["remixflow/static/**/*"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["remixflow"]
+artifacts = ["remixflow/static/**/*"]

remixflow-0.1.0/remixflow/__init__.py

@@ -0,0 +1,12 @@
+"""RemixFlow — an AI music evolution platform (see PRD.md).
+
+This package hosts the FastAPI backend: song import, feature extraction, a
+pluggable steering/generation engine, an evolution tree, A/B comparison,
+morphing, and preference learning.
+"""
+
+__version__ = "0.1.0"
+
+from .app import create_app
+
+__all__ = ["create_app", "__version__"]

remixflow-0.1.0/remixflow/__main__.py

@@ -0,0 +1,36 @@
+"""CLI entrypoint: ``python -m remixflow serve`` / ``remixflow serve``."""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="remixflow", description="RemixFlow server")
+    parser.add_argument("--version", action="version", version=f"remixflow {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    serve = sub.add_parser("serve", help="Run the API + UI server")
+    serve.add_argument("--host", default="127.0.0.1")
+    # 8770 default: this host runs other services on 8000 and 8188 (llama.cpp).
+    serve.add_argument("--port", type=int, default=8770)
+    serve.add_argument("--reload", action="store_true", help="Auto-reload (dev)")
+
+    args = parser.parse_args()
+    if args.command in (None, "serve"):
+        import uvicorn
+
+        host = getattr(args, "host", "127.0.0.1")
+        port = getattr(args, "port", 8000)
+        reload = getattr(args, "reload", False)
+        # Import string form enables --reload.
+        uvicorn.run("remixflow.server:app", host=host, port=port, reload=reload,
+                    factory=False)
+    else:  # pragma: no cover
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

remixflow-0.1.0/remixflow/app.py

@@ -0,0 +1,281 @@
+"""FastAPI application: import, steering, generation, evolution tree, A/B,
+morphing, and preference learning. Serves the built React UI when present."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, File, HTTPException, Query, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import __version__
+from .audio.io import available as audio_available
+from .config import STATIC_DIR, Settings
+from .generation import list_generators
+from .jobs import JobManager
+from .models import GenerateRequest, LivingRequest, MorphRequest, PresetCreate, RateRequest
+from .params import controls_manifest
+from .presets import PresetStore
+from .service import RemixService, ServiceError
+from .store import Store
+
+ALLOWED_EXT = {".mp3", ".wav", ".flac", ".ogg"}
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or Settings.from_env()
+    store = Store(settings.data_dir)
+    service = RemixService(store)
+    jobs = JobManager(max_workers=1)
+    presets = PresetStore(settings.data_dir)
+
+    app = FastAPI(title="RemixFlow", version=__version__)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.state.store = store
+    app.state.service = service
+    app.state.settings = settings
+    app.state.jobs = jobs
+
+    def get_service() -> RemixService:
+        return service
+
+    # --- meta ------------------------------------------------------------
+
+    @app.get("/api/health")
+    def health() -> dict:
+        return {
+            "status": "ok",
+            "version": __version__,
+            "audio_backend": audio_available(),
+            "backends": list_generators(),
+        }
+
+    @app.get("/api/controls")
+    def controls() -> dict:
+        """The full steering control surface for the UI to render."""
+        return controls_manifest()
+
+    @app.get("/api/backends")
+    def backends() -> list:
+        return list_generators()
+
+    # --- songs -----------------------------------------------------------
+
+    @app.post("/api/songs")
+    async def import_song(
+        file: UploadFile = File(...),
+        title: str = Query(default=""),
+        svc: RemixService = Depends(get_service),
+    ) -> dict:
+        ext = Path(file.filename or "").suffix.lower()
+        if ext not in ALLOWED_EXT:
+            raise HTTPException(400, f"Unsupported format {ext!r}. Allowed: {sorted(ALLOWED_EXT)}")
+
+        max_bytes = settings.max_upload_mb * 1024 * 1024
+        data = await file.read(max_bytes + 1)
+        if len(data) > max_bytes:
+            raise HTTPException(413, f"File exceeds {settings.max_upload_mb} MB limit.")
+
+        with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tmp:
+            tmp.write(data)
+            tmp_path = tmp.name
+        try:
+            song, root = svc.import_song(tmp_path, title, file.filename or "")
+        except ServiceError as exc:
+            raise HTTPException(422, str(exc))
+        finally:
+            os.unlink(tmp_path)
+        return {"song": song.model_dump(), "root": root.model_dump()}
+
+    @app.get("/api/songs")
+    def list_songs() -> list:
+        return [s.model_dump() for s in store.list_songs()]
+
+    @app.get("/api/songs/{song_id}")
+    def get_song(song_id: str) -> dict:
+        song = store.get_song(song_id)
+        if not song:
+            raise HTTPException(404, "Song not found")
+        return song.model_dump()
+
+    @app.delete("/api/songs/{song_id}")
+    def delete_song(song_id: str) -> dict:
+        if not store.delete_song(song_id):
+            raise HTTPException(404, "Song not found")
+        return {"deleted": song_id}
+
+    @app.get("/api/songs/{song_id}/tree")
+    def get_tree(song_id: str) -> dict:
+        tree = store.tree(song_id)
+        if tree is None:
+            raise HTTPException(404, "Song not found")
+        return tree.model_dump()
+
+    @app.get("/api/songs/{song_id}/preferences")
+    def preferences(song_id: str, svc: RemixService = Depends(get_service)) -> dict:
+        if not store.get_song(song_id):
+            raise HTTPException(404, "Song not found")
+        return svc.preference_profile(song_id)
+
+    # --- variants --------------------------------------------------------
+
+    @app.get("/api/variants/{variant_id}")
+    def get_variant(variant_id: str) -> dict:
+        v = store.get_variant(variant_id)
+        if not v:
+            raise HTTPException(404, "Variant not found")
+        return v.model_dump()
+
+    @app.post("/api/generate", status_code=202)
+    def generate(
+        req: GenerateRequest,
+        backend: str | None = Query(default=None),
+        seed: int | None = Query(default=None),
+        svc: RemixService = Depends(get_service),
+    ) -> dict:
+        """Enqueue a generation job. Returns a job the client polls; real model
+        backends (ACE-Step) run for tens of seconds, so this is never blocking."""
+        parent = store.get_variant(req.parent_id)
+        if parent is None:
+            raise HTTPException(422, f"Unknown parent variant {req.parent_id!r}.")
+
+        def work(report) -> dict:
+            report(0.05, "Preparing…")
+            report(0.15, f"Generating with {backend or 'default'} backend…")
+            variant = svc.generate(req, backend=backend, seed=seed)
+            report(0.98, "Finalizing…")
+            return variant.model_dump()
+
+        job = jobs.submit("generate", work, song_id=parent.song_id)
+        return job.to_dict()
+
+    @app.get("/api/jobs/{job_id}")
+    def get_job(job_id: str) -> dict:
+        job = jobs.get(job_id)
+        if not job:
+            raise HTTPException(404, "Job not found")
+        return job.to_dict()
+
+    @app.get("/api/jobs")
+    def recent_jobs() -> list:
+        return [j.to_dict() for j in jobs.recent()]
+
+    @app.post("/api/generate/sync")
+    def generate_sync(
+        req: GenerateRequest,
+        backend: str | None = Query(default=None),
+        seed: int | None = Query(default=None),
+        svc: RemixService = Depends(get_service),
+    ) -> dict:
+        """Blocking generation — convenient for tests/scripts and fast backends."""
+        try:
+            variant = svc.generate(req, backend=backend, seed=seed)
+        except ServiceError as exc:
+            raise HTTPException(422, str(exc))
+        return variant.model_dump()
+
+    @app.post("/api/morph")
+    def morph(req: MorphRequest, svc: RemixService = Depends(get_service)) -> dict:
+        try:
+            variant = svc.morph(req)
+        except ServiceError as exc:
+            raise HTTPException(422, str(exc))
+        return variant.model_dump()
+
+    @app.post("/api/variants/{variant_id}/rate")
+    def rate(variant_id: str, req: RateRequest, svc: RemixService = Depends(get_service)) -> dict:
+        try:
+            variant = svc.rate(variant_id, req.rating)
+        except ServiceError as exc:
+            raise HTTPException(404, str(exc))
+        return variant.model_dump()
+
+    # --- Living Mode (PRD Phase 2) ---------------------------------------
+
+    @app.post("/api/living", status_code=202)
+    def living(
+        req: LivingRequest,
+        backend: str | None = Query(default=None),
+        svc: RemixService = Depends(get_service),
+    ) -> dict:
+        """Enqueue a Living segment render. Poll the returned job; its result is a
+        segment {audio_url, next_index, ...}. Call again with start_index=next_index
+        for a seamless continuation (Living Repeat)."""
+        if not store.get_song(req.song_id):
+            raise HTTPException(404, "Song not found")
+
+        def work(report) -> dict:
+            report(0.02, "Starting Living…")
+            return svc.living_segment(req, backend=backend, progress=report)
+
+        job = jobs.submit("living", work, song_id=req.song_id)
+        return job.to_dict()
+
+    @app.get("/api/presets")
+    def list_presets() -> list:
+        return [p.model_dump() for p in presets.list()]
+
+    @app.post("/api/presets", status_code=201)
+    def create_preset(req: PresetCreate) -> dict:
+        return presets.add(req.name, req.params).model_dump()
+
+    @app.delete("/api/presets/{preset_id}")
+    def delete_preset(preset_id: str) -> dict:
+        if not presets.delete(preset_id):
+            raise HTTPException(404, "Preset not found (built-in presets can't be deleted)")
+        return {"deleted": preset_id}
+
+    @app.get("/api/living/audio/{seg_id}")
+    def living_audio(seg_id: str) -> FileResponse:
+        # seg_id is server-minted (live_<hex>); constrain to that shape.
+        if not seg_id.startswith("live_") or "/" in seg_id or ".." in seg_id:
+            raise HTTPException(400, "Bad segment id")
+        path = store.audio_dir / f"{seg_id}.wav"
+        if not path.exists():
+            raise HTTPException(404, "Segment not found")
+        return FileResponse(str(path), media_type="audio/wav")
+
+    @app.get("/api/audio/{variant_id}")
+    def get_audio(variant_id: str) -> FileResponse:
+        v = store.get_variant(variant_id)
+        if not v or not v.audio_path or not Path(v.audio_path).exists():
+            raise HTTPException(404, "Audio not found")
+        return FileResponse(v.audio_path, media_type="audio/wav")
+
+    # --- static frontend (built React app) -------------------------------
+
+    if STATIC_DIR.exists() and (STATIC_DIR / "index.html").exists():
+        app.mount("/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")
+
+        @app.get("/")
+        def index() -> FileResponse:
+            return FileResponse(STATIC_DIR / "index.html")
+
+        @app.exception_handler(404)
+        async def spa_fallback(request, exc):  # noqa: ANN001
+            # Serve the SPA shell for client-side routes, but keep API 404s real.
+            if request.url.path.startswith("/api/"):
+                return JSONResponse({"detail": "Not found"}, status_code=404)
+            return FileResponse(STATIC_DIR / "index.html")
+    else:
+
+        @app.get("/")
+        def index_dev() -> dict:
+            return {
+                "app": "RemixFlow API",
+                "version": __version__,
+                "note": "Frontend not built. Run the Vite dev server, or build it "
+                        "so it is served here. See README.",
+                "docs": "/docs",
+            }
+
+    return app

remixflow-0.1.0/remixflow/audio/__init__.py

@@ -0,0 +1 @@
+"""Audio I/O, analysis, and DSP helpers."""

remixflow-0.1.0/remixflow/audio/analysis.py

@@ -0,0 +1,121 @@
+"""Feature extraction and the 'Musical DNA' embedding (PRD §1, §2, Advanced).
+
+Everything here degrades gracefully: if ``librosa`` is missing we still return
+cheap descriptors computed with NumPy (duration, RMS energy, a coarse spectral
+centroid, and a deterministic embedding), flagging ``analyzed=False`` so the UI
+can show what is estimated vs. measured.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..models import AudioFeatures
+from .io import Clip
+
+_PITCH_CLASSES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+EMBED_DIM = 16
+#: Feature extraction runs at this rate — CQT/beat/MFCC are several× cheaper at
+#: 22 kHz than 44.1 kHz with negligible impact on these descriptors.
+ANALYSIS_SR = 22050
+
+
+def _mono_at_analysis_sr(mono: np.ndarray, sr: int):
+    """Downsample mono audio to ANALYSIS_SR (via librosa) for cheaper analysis."""
+    if sr and sr > ANALYSIS_SR:
+        import librosa  # type: ignore
+
+        return librosa.resample(mono, orig_sr=sr, target_sr=ANALYSIS_SR), ANALYSIS_SR
+    return mono, sr
+
+
+def _spectral_centroid_np(mono: np.ndarray, sr: int) -> float:
+    """A dependency-free spectral centroid (Hz) over the whole clip."""
+    if mono.size == 0 or sr == 0:
+        return 0.0
+    spec = np.abs(np.fft.rfft(mono * np.hanning(mono.size)))
+    freqs = np.fft.rfftfreq(mono.size, d=1.0 / sr)
+    total = spec.sum()
+    return float((freqs * spec).sum() / total) if total > 0 else 0.0
+
+
+def _fallback_embedding(mono: np.ndarray, sr: int) -> list[float]:
+    """A stable, low-cost latent vector derived from band energies.
+
+    Not a learned embedding — a stand-in with the right *shape* and stability
+    so the similarity evaluator and morph feature work end-to-end until a real
+    music encoder backend is plugged into :func:`embed`.
+    """
+    if mono.size == 0:
+        return [0.0] * EMBED_DIM
+    spec = np.abs(np.fft.rfft(mono))
+    if spec.sum() == 0:
+        return [0.0] * EMBED_DIM
+    bands = np.array_split(spec, EMBED_DIM)
+    vec = np.array([b.mean() for b in bands], dtype=np.float64)
+    norm = np.linalg.norm(vec)
+    return (vec / norm).tolist() if norm > 0 else vec.tolist()
+
+
+def analyze(clip: Clip) -> AudioFeatures:
+    """Extract descriptors from a clip, using librosa when available."""
+    mono = clip.to_mono().astype(np.float32)
+    feats = AudioFeatures(
+        duration_sec=round(clip.duration, 3),
+        sample_rate=clip.sample_rate,
+        rms_energy=float(np.sqrt(np.mean(mono**2))) if mono.size else 0.0,
+    )
+
+    try:
+        import librosa  # type: ignore
+
+        y, sr = _mono_at_analysis_sr(mono, clip.sample_rate)
+        tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+        feats.tempo_bpm = round(float(np.atleast_1d(tempo)[0]), 2)
+        feats.spectral_centroid = round(
+            float(np.mean(librosa.feature.spectral_centroid(y=y, sr=sr))), 2
+        )
+        chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+        feats.key = _PITCH_CLASSES[int(np.argmax(chroma.mean(axis=1)))]
+        feats.embedding = embed(clip)
+        feats.analyzed = True
+        feats.note = "librosa"
+    except Exception as exc:  # librosa missing or failed — cheap fallback.
+        feats.spectral_centroid = round(_spectral_centroid_np(mono, clip.sample_rate), 2)
+        feats.embedding = _fallback_embedding(mono, clip.sample_rate)
+        feats.analyzed = False
+        feats.note = f"estimated (librosa unavailable: {type(exc).__name__})"
+
+    return feats
+
+
+def embed(clip: Clip) -> list[float]:
+    """Return the Musical DNA embedding for a clip.
+
+    Uses MFCC statistics via librosa when available (a reasonable timbral
+    fingerprint), else the NumPy band-energy fallback. This is the seam where a
+    real learned music encoder (CLAP / MERT / MusicFM) plugs in later.
+    """
+    mono = clip.to_mono().astype(np.float32)
+    try:
+        import librosa  # type: ignore
+
+        y, sr = _mono_at_analysis_sr(mono, clip.sample_rate)
+        mfcc = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=EMBED_DIM)
+        vec = mfcc.mean(axis=1).astype(np.float64)
+        norm = np.linalg.norm(vec)
+        return (vec / norm).tolist() if norm > 0 else vec.tolist()
+    except Exception:
+        return _fallback_embedding(mono, clip.sample_rate)
+
+
+def similarity(a: list[float], b: list[float]) -> float:
+    """Cosine similarity mapped to [0, 1] — the identity-preservation score."""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    va, vb = np.asarray(a), np.asarray(b)
+    denom = np.linalg.norm(va) * np.linalg.norm(vb)
+    if denom == 0:
+        return 0.0
+    cos = float(np.dot(va, vb) / denom)
+    return round(max(0.0, min(1.0, (cos + 1.0) / 2.0)), 4)