auroramusic/README.md

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 to run this backend on a machine with a GPU.

Quick start (mock backend, any machine)

1. Infra

docker compose up -d postgres redis

2. API

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)

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)

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.