ACE-Step 文本生成音乐（ACE-Step Text To Music）

使用兼容 ACE-Step 的 API 后端处理“文本生成歌曲”（prompt-to-song）和“歌词生成歌曲”（lyrics-to-song）请求。该技能不安装、也不打包 ACE-Step 本身、模型权重或 API 服务端。

前提条件

使用本技能前，请确保您已可访问一个兼容 ACE-Step 的 API 后端。该后端可以是本地服务器（通常位于 http://127.0.0.1:8001），也可以是远程兼容的端点。若后端缺失或未运行，本技能将无法生成音乐。

快速开始

python3 {baseDir}/scripts/generate.py --prompt "一首关于涌起海浪的俏皮海滩流行曲"
python3 {baseDir}/scripts/generate.py --prompt "明亮吉他伴奏的欢快独立流行曲" --lyrics-file /path/to/lyrics.txt --duration 60

默认参数针对快速本地迭代进行了优化：

• batch_size=1：除非显式请求，否则避免生成重复变体
• audio_format=mp3
• sample_mode=text2music
• thinking=false：仅当用户明确要求更重的 LM 辅助生成时才启用
• 生成完成的音频文件将被复制至稳定输出目录，而非仅保留临时 API 路径

适用场景

• 已存在兼容 ACE-Step 的 API 后端（常见为本地服务器 http://127.0.0.1:8001，也可能是远程端点）
• 用户需要文本生成音乐、歌词生成歌曲，或快速风格变体
• 用户希望使用单条命令完成提交、轮询及返回已保存文件的全流程
• 用户希望在本地生成音乐，并在 Clawatch 上播放
• 用户已具备本地或远程兼容 ACE-Step 的后端访问权限

运行方式

# 基础提示词
python3 {baseDir}/scripts/generate.py --prompt "一首关于日出海浪的俏皮合成器流行曲"

# 指定歌词文件
python3 {baseDir}/scripts/generate.py 
  --prompt "轻快可爱的夏日海滩歌曲" 
  --lyrics-file /path/to/lyrics.txt 
  --duration 60

# 生成两个变体
python3 {baseDir}/scripts/generate.py 
  --prompt "梦幻都市流行海洋律动" 
  --duration 45 
  --batch-size 2

# 仅在必要时启用更重的 LM 规划
python3 {baseDir}/scripts/generate.py 
  --prompt "一首描绘风暴转为平静的史诗级配乐" 
  --duration 60 
  --thinking

常用命令行参数：

• --duration 10..600
• --lyrics 或 --lyrics-file
• --batch-size 1..8
• --thinking
• --model acestep-v15-turbo
• --out-dir /path/to/output
• --base-url http://127.0.0.1:8001：用于本地后端
• --base-url https://your-remote-endpoint：用于远程后端

Clawatch 播放支持

若用户还希望在 Clawatch 上播放生成结果，请按以下步骤操作：

1. 运行生成器脚本，并等待其输出已保存的音频文件路径。
2. 从脚本输出或 manifest.json 中选取最终的 .mp3 文件路径。
3. 调用 clawatch_play_audio，传入以下参数：
   • imei：目标手表的明确 IMEI 号
   • filePath：已保存的本地音频文件路径
   • title：可选的简短标签

若辅助工具已将音频复制至稳定的本地路径，则请勿直接传递 ACE-Step 返回的临时 URL；应优先使用已保存的本地文件路径。

配置方式

脚本按如下优先级加载配置：命令行参数 > 环境变量 > OpenClaw 技能配置。

支持的环境变量：

• ACESTEP_API_BASE_URL
• ACESTEP_API_KEY
• ACESTEP_OUTPUT_DIR

可通过 ACESTEP_API_BASE_URL 环境变量或 OpenClaw 配置项，在本地与远程兼容 ACE-Step 后端之间切换。

可选的 OpenClaw 配置（位于 ~/.openclaw/openclaw.json）：

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

注意事项

• 如有需要，可先检查后端健康状态：curl http://127.0.0.1:8001/health，或对您的远程端点执行相同路径的请求
• 若 API 返回临时 /v1/audio?path=... 类型的 URL，辅助工具会将对应文件复制至指定输出目录，并写入 manifest.json
• 为高效进行提示词迭代，建议默认使用 batch-size 1；仅当用户明确要求多个变体时再提高该值