# Aurora Music

A generative AI music platform: describe a song in a text prompt (optionally
with your own lyrics) and get back a full track with instrumentation and,
in vocals mode, sung vocals. Accounts, a personal library, and a public
feed with likes.

## Architecture

```
apps/web       Next.js 16 frontend — auth, create, library, feed
apps/api       FastAPI backend — auth, songs, likes, enqueues generation jobs
apps/worker    RQ worker — pulls jobs off Redis, calls a generation provider
packages/db    Shared SQLAlchemy models used by both api and worker
packages/inference  Pluggable MusicGenerationProvider interface + backends
```

Generation is async: the API creates a `Song` row (`status=pending`) and
enqueues a job; the worker picks it up, calls whichever provider is
configured, writes the resulting audio to `media/`, and flips the row to
`completed`/`failed`. The frontend polls while a song is in flight.

The generation step is pluggable (`packages/inference/factory.py`,
switched via `GENERATION_BACKEND`):

- `mock` (default, used below) — synthesizes a quick procedural clip.
  No GPU, no heavy deps. Good enough to build and test the whole product.
- `diffrhythm` — a real open-source model (vocals + instrumentation from a
  prompt + lyrics). Needs an NVIDIA GPU. See
  [infra/gpu-provider/README.md](infra/gpu-provider/README.md) to run this
  backend on a machine with a GPU.

## Quick start (mock backend, any machine)

**1. Infra**

```bash
docker compose up -d postgres redis
```

**2. API**

```bash
cd apps/api
python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ../../packages/db -e ../../packages/inference
cp .env.example .env   # edit MEDIA_DIR to an absolute path
.venv/bin/alembic upgrade head
.venv/bin/uvicorn app.main:app --reload --port 8000
```

**3. Worker** (separate terminal)

```bash
cd apps/worker
python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ../../packages/db -e ../../packages/inference
cp .env.example .env   # MEDIA_DIR must match the API's
.venv/bin/python run_worker.py
```

**4. Web** (separate terminal)

```bash
cd apps/web
npm install
npm run dev
```

Open http://localhost:3000, sign up, and create a song — it'll show as
"Generating…" in your library for a few seconds, then become playable.

## Switching to real generation

Everything above works identically once you switch backends — the API,
worker, and frontend don't change. Only the worker's `.env` changes
(`GENERATION_BACKEND=diffrhythm` plus a few `DIFFRHYTHM_*` vars). See
[infra/gpu-provider/README.md](infra/gpu-provider/README.md).