feat(deploy): m7 — hf spaces readme + cache bootstrap + zerogpu decorator

README.md

@@ -1,29 +1,22 @@
 ---
 title: ACE Music Studio
-emoji: "🎵"
+emoji: 🎵
 colorFrom: gray
 colorTo: gray
 sdk: gradio
-sdk_version: "5.50.0"
+sdk_version: 6.14.0
 app_file: app.py
-python_version: "3.11"
-suggested_hardware: zero-a10g
-hf_oauth: false
+pinned: false
+license: mit
+short_description: Open-source song generation studio on ACE-Step 1.5 XL SFT — Generate, Cover, Extend, Edit, draft Lyrics.
 preload_from_hub:
-  - ACE-Step/acestep-v15-xl-sft *.safetensors,config.json,scheduler/*,vae/*,tokenizer/*
-  - Qwen/Qwen2.5-7B-Instruct *.safetensors,config.json,tokenizer*
-  - facebook/htdemucs_ft *.th
+- ACE-Step/Ace-Step1.5 vae/diffusion_pytorch_model.safetensors,vae/config.json,encoder/pytorch_model.bin,encoder/config.json,encoder/tokenizer.json
+- ACE-Step/acestep-v15-xl-sft model.safetensors
 ---
 
 # ACE Music Studio
 
-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).
-
-[![Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Spaces-Live-FFFFFF?style=flat-square)](https://huggingface.co/spaces/techfreakworm/ace-music-studio)
-[![GitHub stars](https://img.shields.io/github/stars/techfreakworm/ace-music-studio?style=flat-square)](https://github.com/techfreakworm/ace-music-studio/stargazers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-FFFFFF?style=flat-square)](LICENSE)
-[![Python 3.11](https://img.shields.io/badge/Python-3.11-FFFFFF?style=flat-square&logo=python&logoColor=white)](pyproject.toml)
-[![Backed by ACE-Step](https://img.shields.io/badge/backend-ACE--Step%201.5%20XL%20SFT-FFFFFF?style=flat-square)](https://github.com/ace-step/ACE-Step-1.5)
+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 Qwen 2.5 for lyrics drafting and Demucs for stem separation. Runs locally on **Apple Silicon (MPS+MLX)** or **NVIDIA (CUDA)**, deploys to **Hugging Face Spaces (ZeroGPU)**.
 
 → **Live demo:** https://huggingface.co/spaces/techfreakworm/ace-music-studio
 
@@ -31,7 +24,7 @@ A single-process Gradio app that wraps [ACE-Step 1.5 XL SFT](https://github.com/
 
 ## What's inside
 
-Five tabs. One ACE-Step pipeline underneath. Progressive disclosure — defaults stay short and reveal advanced controls only when asked.
+Five modes. One ACE-Step pipeline underneath. Progressive disclosure — defaults stay short and reveal advanced controls only when asked.
 
 | Mode | Inputs | What it does |
 |---|---|---|
@@ -41,38 +34,43 @@ Five tabs. One ACE-Step pipeline underneath. Progressive disclosure — defaults
 | **Edit** | source audio + segment + target lyrics | Repaint a segment OR flow-morph caption-to-caption |
 | **Lyrics** | brief + structure | Qwen 2.5 7B drafts structurally-tagged lyrics |
 
-Every song tab supports stacked LoRAs — 4 bundled presets (RapMachine, Chinese Rap, Lyric2Vocal, Text2Samples) plus arbitrary `.safetensors` uploads.
+Every song mode supports a single stacked LoRA — bundled presets plus arbitrary `.safetensors` uploads. The preset registry ships with the official ACE-Step LoRAs published on HF:
+
+- [ACE-Step/ACE-Step-v1-chinese-rap-LoRA](https://huggingface.co/ACE-Step/ACE-Step-v1-chinese-rap-LoRA)
+- [ACE-Step/ACE-Step-v1.5-chinese-new-year-LoRA](https://huggingface.co/ACE-Step/ACE-Step-v1.5-chinese-new-year-LoRA)
+
+After every song generation, three post-process actions sit beneath the player: **Demucs stem separation**, **pyloudnorm normalisation to -14 LUFS**, and **MP3 320k export via ffmpeg**.
 
 ---
 
-## Quick start (local)
+## Local setup
 
-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).
+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). On NVIDIA, ~24 GB VRAM.
 
 ```bash
 git clone https://github.com/techfreakworm/ace-music-studio
 cd ace-music-studio
-bash setup.sh
+bash setup.sh             # creates .venv, installs requirements
 source .venv/bin/activate
-python app.py    # http://127.0.0.1:7860
+python app.py             # http://127.0.0.1:7860
 ```
 
-First launch downloads the ACE-Step + Qwen + Demucs weights into your HF cache (`~/.cache/huggingface/hub/`). Subsequent starts are fast.
+`setup.sh` detects Apple Silicon and adds `requirements-mac.txt` (MLX-LM + the [`clockworksquirrel/ace-step-apple-silicon`](https://github.com/clockworksquirrel/ace-step-apple-silicon) fork). First launch downloads weights into your HF cache (`~/.cache/huggingface/hub/`).
 
-**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.
+`PYTORCH_ENABLE_MPS_FALLBACK=1` is set automatically by `app.py` so the few MPS-unsupported ops degrade to CPU.
 
-## Quick start (HF Spaces)
+## HF Spaces deploy
 
 ```bash
-git remote add space https://huggingface.co/spaces/techfreakworm/ace-music-studio
+git remote add space https://huggingface.co/spaces/<your-handle>/ace-music-studio
 git push space main
 ```
 
-`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.
+`preload_from_hub` (this README's frontmatter) pre-downloads the ACE-Step 1.5 XL SFT umbrella weights at build time. `app._bootstrap_spaces_cache()` runs once at module init when `SPACE_ID` is set, symlinking the HF cache into the fork's expected `<site-packages>/checkpoints/` layout so the pipeline finds them on first request. `@spaces.GPU(duration=180)` decorates the click handlers — on Spaces it gates them to a ZeroGPU worker, locally it's a no-op.
 
 ## Architecture
 
-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/).
+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 and [`docs/superpowers/plans/2026-05-18-ace-music-studio.md`](docs/superpowers/plans/2026-05-18-ace-music-studio.md) for the implementation plan.
 
 ## License
 
@@ -80,4 +78,6 @@ MIT for the app code (see `LICENSE`). ACE-Step 1.5 XL SFT, Qwen 2.5 7B Instruct,
 
 ## Credits
 
-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).
+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).
+
+Made with ❤️ by [Mayank Gupta](https://huggingface.co/techfreakworm).

app.py

@@ -28,9 +28,10 @@ state gives us the sidebar "active item" highlight for free via CSS
 DO NOT switch this back to ``gr.Tabs`` — that produces top-positioned
 horizontal tabs which contradicts the wireframes.
 
-On HF Spaces, ``_bootstrap()`` runs once on import to mirror the
-read-only preload cache into a writable tree. On Mac/Linux locally,
-it's a no-op until M7.
+On HF Spaces (``SPACE_ID`` env present), ``_bootstrap_spaces_cache()``
+runs once on import to symlink HF hub cache snapshots into the
+acestep-apple-silicon fork's ``<site-packages>/checkpoints/`` layout.
+On Mac/Linux locally, it's a no-op.
 """
 
 from __future__ import annotations
@@ -67,6 +68,78 @@ def get_backend() -> be.ACEStepStudioBackend:
     return _BACKEND
 
 
+def _bootstrap_spaces_cache() -> None:
+    """On HF Spaces, mirror the HF hub cache into the site-packages checkpoints/ dir.
+
+    The acestep-apple-silicon fork resolves checkpoints relative to its own install
+    location (``.venv/.../site-packages/checkpoints/``). HF Spaces puts model weights
+    in the HF hub cache. This bootstrap snapshot-downloads the two required repos
+    into the cache (using preload mirror if available) and then symlinks each
+    snapshot child into ``checkpoints/`` so the fork's resolver finds them.
+
+    Local Mac/CUDA: no-op (guarded by ``SPACE_ID`` env var).
+    """
+    if not os.getenv("SPACE_ID"):
+        return
+
+    import site
+
+    from huggingface_hub import snapshot_download
+
+    site_pkgs = site.getsitepackages()[0]
+    target_dir = Path(site_pkgs) / "checkpoints"
+
+    if target_dir.exists():
+        return  # already bootstrapped
+
+    hf_home = os.getenv("HF_HOME", "/home/user/.cache/huggingface")
+
+    # Download Ace-Step1.5 umbrella (vae + encoder).
+    umbrella_path = snapshot_download(
+        repo_id="ACE-Step/Ace-Step1.5",
+        cache_dir=hf_home,
+    )
+
+    # Download the XL SFT diffusion variant.
+    xl_sft_path = snapshot_download(
+        repo_id="ACE-Step/acestep-v15-xl-sft",
+        cache_dir=hf_home,
+    )
+
+    # Merge both snapshots into ``checkpoints/`` via symlinks.
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for src_path in [umbrella_path, xl_sft_path]:
+        for child in Path(src_path).iterdir():
+            link = target_dir / child.name
+            if not link.exists():
+                link.symlink_to(child)
+
+
+def _maybe_spaces_gpu():
+    """Return ``@spaces.GPU(duration=180)`` on HF Spaces, otherwise a no-op decorator.
+
+    The decorator MUST be applied at module load time — ZeroGPU's startup
+    analyzer doesn't see runtime decoration. Local dev is a transparent pass-through.
+    """
+    if os.getenv("SPACE_ID"):
+        try:
+            import spaces
+
+            return spaces.GPU(duration=180)
+        except ImportError:
+            pass
+
+    def _noop(fn):
+        return fn
+
+    return _noop
+
+
+# Run cache bootstrap at module import so HF Spaces' startup analyzer sees
+# the symlinks before the lazy backend singleton is constructed on first click.
+_bootstrap_spaces_cache()
+
+
 def _safe_call(fn, *args, **kwargs):
     """Wrap a mode handler so all known exceptions become friendly gr.Error toasts.
 
@@ -190,6 +263,7 @@ def on_lora_strength_change(state, strength: float):
     return new_state, _active_md(new_state["name"], float(strength), kind)
 
 
+@_maybe_spaces_gpu()
 def on_generate_click(
     prompt: str,
     lyrics: str,
@@ -218,6 +292,7 @@ def on_generate_click(
     return out_path, meta, new_history
 
 
+@_maybe_spaces_gpu()
 def on_cover_click(
     ref_audio,
     prompt: str,
@@ -249,6 +324,7 @@ def on_cover_click(
     return out_path, meta, new_history
 
 
+@_maybe_spaces_gpu()
 def on_extend_click(
     seed_audio,
     extra_prompt: str,
@@ -288,6 +364,7 @@ def on_extend_click(
     return out_path, meta, new_history
 
 
+@_maybe_spaces_gpu()
 def on_draft_lyrics(
     brief: str,
     structure: str,
@@ -365,6 +442,7 @@ def on_export_mp3(audio_path):
     return gr.File(value=str(out), visible=True)
 
 
+@_maybe_spaces_gpu()
 def on_edit_click(
     source_audio,
     sub_mode: str,
@@ -495,14 +573,6 @@ MODE_CHOICES = [
 ]
 
 
-def _bootstrap() -> None:
-    """HF Spaces: mirror read-only preload cache into a writable tree.
-
-    Local Mac/CUDA: no-op. Implemented at M7 when we wire deployment.
-    """
-    pass
-
-
 def build_app() -> gr.Blocks:
     device = ace_pipeline.detect_device()
 
@@ -762,7 +832,6 @@ def build_app() -> gr.Blocks:
 
 
 if __name__ == "__main__":
-    _bootstrap()
     demo = build_app()
     demo.queue(default_concurrency_limit=1)
     demo.launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", 7860)))

pyproject.toml

@@ -10,6 +10,10 @@ requires-python = ">=3.11,<3.12"
 [tool.ruff]
 line-length = 110
 target-version = "py311"
+# checkpoints/ holds downloaded model code shipped by upstream HF repos —
+# linting third-party drop-ins isn't our concern. output/ and research/
+# are runtime artefacts / scratch.
+extend-exclude = ["checkpoints", "output", "research", ".venv"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "RUF"]

requirements.txt

@@ -11,3 +11,7 @@ librosa>=0.10
 huggingface_hub>=0.25
 numpy>=1.26,<2
 ace-step @ git+https://github.com/ace-step/ACE-Step-1.5.git
+# HF Spaces ZeroGPU. Do NOT pin — HF's ZeroGPU build injects its own version
+# and a pin causes pip-resolve failure. Locally the `import spaces` in
+# app._maybe_spaces_gpu() is wrapped in try/except so absence is fine.
+spaces; sys_platform == "linux"