Metadata-Version: 2.4
Name: remixflow
Version: 0.1.1
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. |
