# ace-step

ACE-Step 1.5 — Apache 2.0 open-source music generation foundation
model. Hybrid diffusion + LLM. Generates lyric-aware multi-minute
songs (vocals + instrumentation).

| | |
|---|---|
| host | `irv-ml1` |
| port | `8210` |
| GPU | A6000 (`device_ids: ["1"]`) |
| VRAM | ~10-12 GB during inference |
| upstream | https://github.com/ace-step/ACE-Step |
| license | Apache 2.0 |

## API surface

`infer-api.py` (FastAPI) exposes:

- `GET /health` — liveness, returns 200 once the process is up
  (model is lazy-loaded on first /generate).
- `POST /generate` — body: `ACEStepInput` Pydantic model with
  ~27 params (prompt, lyrics, audio_duration, guidance_scale, etc.).
  Returns `{status, output_path, message}`.

The container does NOT expose the Gradio UI — we override the upstream
default `python3 acestep/gui.py` with `python3 infer-api.py`. If you
want the Gradio UI for ad-hoc experimentation, run a one-off:

```bash
ssh irv-ml1 'docker exec -it ace-step python3 acestep/gui.py --server_name 0.0.0.0 --port 7865'
```

…and port-forward 7865 to your laptop.

## Deploy

```bash
scripts/elway irv-ml1 --playbook playbooks/deploy-ace-step.yaml
```

Idempotent. Cold build is ~10-15 min (CUDA + torch + transformers +
spacy + audio deps). First `/generate` triggers the model download
(~5-10 GB) and warmup (~30-60 s).

## Tunables

See `.env.example` — copy to `.env` on the host (lives at
`/opt/docker/compose/ace-step/.env`, gitignored). Common knobs:

- `ACE_STEP_SHA` — pin upstream commit
- `ACE_STEP_GPU_DEVICES` — GPU index
- `ACE_STEP_*_DIR` — bind-mount paths under `/worktank/ace-step/`