Developer docs / AI Fabric tutorials

Music generation with ACE-Step

  • GPU
  • Volume
  • Image DSL

Take it for a spin

The whole program in one file, ready to run.

music_gen.py
import bladekit
import io

app = bladekit.app("music-gen")

# Checkpoints (~7 GB) are cached on a Volume so only the first run downloads them.
hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)

# ACE-Step requires Python < 3.13; 3.12 is the platform default, so nothing special
# from a Python 3.12 venv too (AI Fabric run-mode matches client and image Python).
# The PyPI "ace_step" package is an incomplete sdist: install from GitHub.
image = (
    bladekit.Image.debian_slim(python_version="3.12")
    .apt_install("git", "ffmpeg")
    # Pin the torch trio first: ACE-Step leaves them unpinned and PyPI's
    # latest torch/torchvision/torchaudio can skew out of sync.
    .pip_install("torch==2.8.0", "torchvision==0.23.0", "torchaudio==2.8.0")
    .pip_install(
        "git+https://github.com/ace-step/ACE-Step.git",
        "hf_transfer",
    )
    .env({"HF_HOME": "/hf-cache", "HF_HUB_ENABLE_HF_TRANSFER": "1"})
)

_pipe = None


@app.function(gpu="RTX-A4500", image=image, timeout=1800, volumes={"/hf-cache": hf_cache})
def generate_music(prompt: str, duration_seconds: int = 15) -> bytes:
    global _pipe
    import soundfile as sf
    from acestep.pipeline_ace_step import ACEStepPipeline

    if _pipe is None:
        # Downloads ACE-Step/ACE-Step-v1-3.5B into the Volume on first use,
        # then loads it on the GPU (~2 min; cached runs skip the download).
        _pipe = ACEStepPipeline(
            checkpoint_dir="/hf-cache/ace-step-v1-3.5b", dtype="bfloat16"
        )

    # The pipeline writes audio to disk and returns [path, ..., params].
    # save_path must end in ".wav" because the format is inferred from the extension.
    outputs = _pipe(
        prompt=prompt,
        lyrics="[instrumental]",
        audio_duration=float(duration_seconds),
        infer_step=27,
        guidance_scale=15.0,
        save_path="/tmp/ace-output.wav",
        format="wav",
    )
    audio_path = outputs[0]

    # Re-encode to WAV in memory so callers always get RIFF/WAV bytes.
    data, sample_rate = sf.read(audio_path)
    buf = io.BytesIO()
    sf.write(buf, data, samplerate=sample_rate, format="WAV")
    return buf.getvalue()


@app.local_entrypoint()
def main():
    import pathlib

    wav = generate_music.remote(
        "upbeat jazz piano trio, swing rhythm, warm recording"
    )
    pathlib.Path("music.wav").write_bytes(wav)
    print(f"Saved music.wav ({len(wav) / 1e3:.0f} KB)")

Run it

  1. ACE-Step needs Python < 3.13, and AI Fabric run-mode requires the client Python to MATCH the image, so create a 3.12 client venv first: uv venv -p 3.12 .venv312 && uv pip install --python .venv312/bin/python bladekit, then use .venv312/bin/blade.
  2. Save as music_gen.py. Run .venv312/bin/blade run music_gen.py.
  3. The PyPI ace_step package is an incomplete sdist (missing half its modules), so the image installs from GitHub instead, with the torch trio pinned so PyPI can't skew torchaudio out of sync.
  4. First run downloads the ~7 GB ACE-Step checkpoints into the hf-cache Volume; later runs skip it. A 15-second clip generates in well under a minute on the A4500.
  5. Your track lands in music.wav locally. Tweak prompt, duration_seconds, or pass real lyrics instead of [instrumental].

Concepts used: Cold start, GPU, Image build

Contact the team

Loading the form…