Spaces:
Running on Zero
Running on Zero
docs: add readme with hf space frontmatter and quick start
Browse files
README.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
title: ACE Music Studio
|
| 3 |
+
emoji: "🎵"
|
| 4 |
+
colorFrom: gray
|
| 5 |
+
colorTo: gray
|
| 6 |
+
sdk: gradio
|
| 7 |
+
sdk_version: "5.50.0"
|
| 8 |
+
app_file: app.py
|
| 9 |
+
python_version: "3.11"
|
| 10 |
+
suggested_hardware: zero-a10g
|
| 11 |
+
hf_oauth: false
|
| 12 |
+
preload_from_hub:
|
| 13 |
+
- ACE-Step/ACE-Step-v1.5-XL-SFT *.safetensors,config.json,scheduler/*,vae/*,tokenizer/*
|
| 14 |
+
- Qwen/Qwen2.5-7B-Instruct *.safetensors,config.json,tokenizer*
|
| 15 |
+
- facebook/htdemucs_ft *.th
|
| 16 |
+
---
|
| 17 |
+
|
| 18 |
+
# ACE Music Studio
|
| 19 |
+
|
| 20 |
+
A single-process Gradio app that wraps [ACE-Step 1.5 XL SFT](https://github.com/ace-step/ACE-Step-1.5) for full-song generation with vocals, with bundled Qwen 2.5 7B for lyrics and Demucs for stem separation. Runs locally on Apple Silicon (MPS+MLX) or NVIDIA (CUDA), deploys to Hugging Face Spaces (ZeroGPU).
|
| 21 |
+
|
| 22 |
+
[](https://huggingface.co/spaces/techfreakworm/ace-music-studio)
|
| 23 |
+
[](https://github.com/techfreakworm/ace-music-studio/stargazers)
|
| 24 |
+
[](LICENSE)
|
| 25 |
+
[](pyproject.toml)
|
| 26 |
+
[](https://github.com/ace-step/ACE-Step-1.5)
|
| 27 |
+
|
| 28 |
+
→ **Live demo:** https://huggingface.co/spaces/techfreakworm/ace-music-studio
|
| 29 |
+
|
| 30 |
+
---
|
| 31 |
+
|
| 32 |
+
## What's inside
|
| 33 |
+
|
| 34 |
+
Five tabs. One ACE-Step pipeline underneath. Progressive disclosure — defaults stay short and reveal advanced controls only when asked.
|
| 35 |
+
|
| 36 |
+
| Mode | Inputs | What it does |
|
| 37 |
+
|---|---|---|
|
| 38 |
+
| **Generate** | prompt + lyrics + tags | Text → full song with vocals + instruments |
|
| 39 |
+
| **Cover** | reference audio + new lyrics | Style transfer from a reference clip |
|
| 40 |
+
| **Extend** | seed audio + extension prompt | Continue an existing song forward |
|
| 41 |
+
| **Edit** | source audio + segment + target lyrics | Repaint a segment OR flow-morph caption-to-caption |
|
| 42 |
+
| **Lyrics** | brief + structure | Qwen 2.5 7B drafts structurally-tagged lyrics |
|
| 43 |
+
|
| 44 |
+
Every song tab supports stacked LoRAs — 4 bundled presets (RapMachine, Chinese Rap, Lyric2Vocal, Text2Samples) plus arbitrary `.safetensors` uploads.
|
| 45 |
+
|
| 46 |
+
---
|
| 47 |
+
|
| 48 |
+
## Quick start (local)
|
| 49 |
+
|
| 50 |
+
Requires **Python 3.11**, ~32 GB free disk for weights, and **128 GB unified memory recommended on Apple Silicon** (M5 Max ideal; M3 Max+ workable).
|
| 51 |
+
|
| 52 |
+
```bash
|
| 53 |
+
git clone https://github.com/techfreakworm/ace-music-studio
|
| 54 |
+
cd ace-music-studio
|
| 55 |
+
bash setup.sh
|
| 56 |
+
source .venv/bin/activate
|
| 57 |
+
python app.py # http://127.0.0.1:7860
|
| 58 |
+
```
|
| 59 |
+
|
| 60 |
+
First launch downloads the ACE-Step + Qwen + Demucs weights into your HF cache (`~/.cache/huggingface/hub/`). Subsequent starts are fast.
|
| 61 |
+
|
| 62 |
+
**Apple Silicon notes:** `PYTORCH_ENABLE_MPS_FALLBACK=1` is set automatically by `app.py`. The Mac path uses the [`clockworksquirrel/ace-step-apple-silicon`](https://github.com/clockworksquirrel/ace-step-apple-silicon) fork for MLX-LM + MPS-DiT hybrid execution.
|
| 63 |
+
|
| 64 |
+
## Quick start (HF Spaces)
|
| 65 |
+
|
| 66 |
+
```bash
|
| 67 |
+
git remote add space https://huggingface.co/spaces/techfreakworm/ace-music-studio
|
| 68 |
+
git push space main
|
| 69 |
+
```
|
| 70 |
+
|
| 71 |
+
`preload_from_hub` in this README pre-downloads ~32 GB of weights at build time. `app._bootstrap()` mirrors the read-only build cache into `~/hf-cache-rw/` then symlinks every snapshot into `./models/<repo>/` so the pipeline finds them locally on first request.
|
| 72 |
+
|
| 73 |
+
## Architecture
|
| 74 |
+
|
| 75 |
+
See [`docs/superpowers/specs/2026-05-18-ace-music-studio-design.md`](docs/superpowers/specs/2026-05-18-ace-music-studio-design.md) for the full design. UI mockups live in [`docs/superpowers/specs/mockups/`](docs/superpowers/specs/mockups/).
|
| 76 |
+
|
| 77 |
+
## License
|
| 78 |
+
|
| 79 |
+
MIT for the app code (see `LICENSE`). ACE-Step 1.5 XL SFT, Qwen 2.5 7B Instruct, and Demucs htdemucs_ft retain their respective upstream licenses (Apache 2.0 / Apache 2.0 / MIT).
|
| 80 |
+
|
| 81 |
+
## Credits
|
| 82 |
+
|
| 83 |
+
ACE-Step by [ACE Studio × StepFun](https://ace-step.github.io/). Apple Silicon port by [clockworksquirrel](https://github.com/clockworksquirrel/ace-step-apple-silicon). Qwen 2.5 by [Alibaba](https://huggingface.co/Qwen). Demucs by [Meta AI](https://github.com/facebookresearch/demucs). Built by [@techfreakworm](https://huggingface.co/techfreakworm).
|