remixflow 0.1.0__py3-none-any.whl

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/__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/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/audio/__init__.py

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

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)

remixflow/audio/io.py

@@ -0,0 +1,87 @@
+"""Audio load/save with graceful degradation.
+
+We prefer ``soundfile`` (libsndfile: WAV/FLAC/OGG) and fall back to
+``librosa``/``audioread`` (which can reach MP3 via ffmpeg when present). All
+imports are lazy so the API boots and serves the UI even in an environment
+with none of the audio stack installed — feature extraction and DSP simply
+report themselves as unavailable rather than crashing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+
+@dataclass
+class Clip:
+    """Mono/stereo float32 audio in memory. Shape: (channels, samples)."""
+
+    samples: np.ndarray  # float32, shape (channels, n)
+    sample_rate: int
+
+    @property
+    def duration(self) -> float:
+        return self.samples.shape[-1] / self.sample_rate if self.sample_rate else 0.0
+
+    def to_mono(self) -> np.ndarray:
+        return self.samples.mean(axis=0) if self.samples.ndim == 2 else self.samples
+
+
+class AudioUnavailable(RuntimeError):
+    """Raised when no audio backend can handle a load/save request."""
+
+
+def load(path: str) -> Clip:
+    """Load an audio file into a :class:`Clip`. Raises AudioUnavailable if the
+    audio stack cannot read it (missing libs / unsupported codec)."""
+    # Try soundfile first — fast and covers WAV/FLAC/OGG.
+    try:
+        import soundfile as sf  # type: ignore
+
+        data, sr = sf.read(path, dtype="float32", always_2d=True)
+        # soundfile gives (n, channels); transpose to (channels, n).
+        return Clip(samples=np.ascontiguousarray(data.T), sample_rate=int(sr))
+    except Exception:
+        pass
+
+    try:
+        import librosa  # type: ignore
+
+        data, sr = librosa.load(path, sr=None, mono=False)
+        if data.ndim == 1:
+            data = data[np.newaxis, :]
+        return Clip(samples=data.astype(np.float32), sample_rate=int(sr))
+    except Exception as exc:  # pragma: no cover - env dependent
+        raise AudioUnavailable(
+            f"Could not decode {path!r}. Install 'soundfile' (WAV/FLAC/OGG) or "
+            f"'librosa'+ffmpeg (MP3). Underlying error: {exc}"
+        ) from exc
+
+
+def save(clip: Clip, path: str) -> None:
+    """Persist a clip to disk (WAV via soundfile)."""
+    try:
+        import soundfile as sf  # type: ignore
+    except Exception as exc:  # pragma: no cover - env dependent
+        raise AudioUnavailable(
+            "Saving audio requires 'soundfile' (pip install soundfile)."
+        ) from exc
+
+    data = clip.samples
+    # soundfile expects (n, channels).
+    out = data.T if data.ndim == 2 else data[:, np.newaxis]
+    sf.write(path, np.clip(out, -1.0, 1.0), clip.sample_rate, subtype="PCM_16")
+
+
+def available() -> bool:
+    """True if at least one decode backend is importable."""
+    for mod in ("soundfile", "librosa"):
+        try:
+            __import__(mod)
+            return True
+        except Exception:
+            continue
+    return False

remixflow/config.py

@@ -0,0 +1,28 @@
+"""Runtime configuration via environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+PKG_ROOT = Path(__file__).resolve().parent
+# Built frontend assets are copied here at package build time (see pyproject).
+STATIC_DIR = PKG_ROOT / "static"
+
+
+@dataclass
+class Settings:
+    data_dir: Path
+    max_upload_mb: int
+    cors_origins: list[str]
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        data_dir = Path(os.environ.get("REMIXFLOW_DATA_DIR", "./remixflow_data")).resolve()
+        origins = os.environ.get("REMIXFLOW_CORS", "*").split(",")
+        return cls(
+            data_dir=data_dir,
+            max_upload_mb=int(os.environ.get("REMIXFLOW_MAX_UPLOAD_MB", "50")),
+            cors_origins=[o.strip() for o in origins if o.strip()],
+        )

remixflow/generation/__init__.py

@@ -0,0 +1,16 @@
+"""Music generation backends. The interface is the important part — real
+diffusion/transformer models (ACE-Step, Stable Audio, MusicGen) implement the
+same :class:`~remixflow.generation.base.Generator` contract."""
+
+from .base import Generator, GenerationResult
+from .dsp import DSPGenerator
+from .registry import get_generator, register_generator, list_generators
+
+__all__ = [
+    "Generator",
+    "GenerationResult",
+    "DSPGenerator",
+    "get_generator",
+    "register_generator",
+    "list_generators",
+]