ACE-Step Text To Music

Use an ACE-Step-compatible API backend for prompt-to-song and lyrics-to-song requests. This skill does not install or bundle ACE-Step, model weights, or the API server.

Prerequisite

Before using this skill, make sure you already have access to an ACE-Step-compatible API backend. This can be a local server, usually at http://127.0.0.1:8001, or a remote compatible endpoint. If the backend is missing or stopped, this skill cannot generate music.

Quick start

python3 {baseDir}/scripts/generate.py --prompt "playful beach pop song about rising waves"
python3 {baseDir}/scripts/generate.py --prompt "happy indie pop with bright guitars" --lyrics-file /path/to/lyrics.txt --duration 60

Defaults are tuned for fast local iteration:

• batch_size=1 to avoid duplicate variants unless explicitly requested
• audio_format=mp3
• sample_mode=text2music
• thinking=false unless the user asks for heavier LM-assisted generation
• finished audio is copied into a stable output folder instead of leaving only temp API paths

When to use

• An ACE-Step-compatible API backend is already available, commonly a local server at http://127.0.0.1:8001 but possibly a remote endpoint
• The user wants text-to-music, lyrics-to-song, or quick style variations
• The user wants a single command that submits, polls, and returns saved files
• The user wants music generated locally and then played on Clawatch
• The user already has access to a local or remote ACE-Step-compatible backend

Run

# Basic prompt
python3 {baseDir}/scripts/generate.py --prompt "playful synth-pop song about sunrise waves"

# With lyrics
python3 {baseDir}/scripts/generate.py \
  --prompt "cute upbeat summer beach song" \
  --lyrics-file /path/to/lyrics.txt \
  --duration 60

# Two variants
python3 {baseDir}/scripts/generate.py \
  --prompt "dreamy city-pop ocean groove" \
  --duration 45 \
  --batch-size 2

# Enable heavier LM planning only when needed
python3 {baseDir}/scripts/generate.py \
  --prompt "cinematic anthem about a storm becoming calm" \
  --duration 60 \
  --thinking

Useful flags:

• --duration 10..600
• --lyrics or --lyrics-file
• --batch-size 1..8
• --thinking
• --model acestep-v15-turbo
• --out-dir /path/to/output
• --base-url http://127.0.0.1:8001 for local backends
• --base-url https://your-remote-endpoint for remote backends

Clawatch playback

If the user also wants the result played on Clawatch:

1. Run the generator and wait for the saved output file paths.
2. Pick the final .mp3 path from the script output or manifest.json.
3. Call clawatch_play_audio with:
   • imei: the explicit watch IMEI
   • filePath: the saved local audio path
   • title: optional short label

Do not pass ACE-Step temp URLs directly if the helper already copied a stable local file. Prefer the saved file path.

Config

The script accepts CLI flags first, then env vars, then OpenClaw skill config.

Supported env vars:

• ACESTEP_API_BASE_URL
• ACESTEP_API_KEY
• ACESTEP_OUTPUT_DIR

Use ACESTEP_API_BASE_URL or the OpenClaw config entry to switch between local and remote ACE-Step-compatible backends.

Optional OpenClaw config in ~/.openclaw/openclaw.json:

{
  skills: {
    entries: {
      "gen-music": {
        baseUrl: "http://127.0.0.1:8001",
        apiKey: "",
        outputDir: "~/Projects/tmp/ace-step"
      }
    }
  }
}

Notes

• Check backend health first if needed: curl http://127.0.0.1:8001/health or the same path on your remote endpoint
• If the API returns temp /v1/audio?path=... URLs, the helper copies those files into the chosen output directory and writes a manifest.json
• Prefer batch-size 1 for efficient prompt iteration; raise it only when the user explicitly wants variants