acestep

ACE-Step 1.5 音乐生成

通过 tools/music_gen.py 开源生成音乐。

云服务提供商：

• acemusic（默认）— 官方 ACE-Step 云 API，使用 XL Turbo（4B）模型和 5Hz LM 思考模式。可从 acemusic.ai/api-key 获取免费 API 密钥。无需 GPU。
• modal — 在 Modal A10G 上自托管 ACE-Step 1.5 XL Turbo（4B DiT，不含 LM）。需要 MODAL_MUSIC_GEN_ENDPOINT_URL。
• runpod — 在 RunPod 上自托管 ACE-Step 2B Turbo。需要 RUNPOD_ACESTEP_ENDPOINT_ID。

设置

# acemusic (recommended — free, best quality, no GPU)
echo "ACEMUSIC_API_KEY=your_key" >> .env
# Get key at https://acemusic.ai/api-key

# Self-hosted (optional fallback)
uv run tools/music_gen.py --setup             # RunPod
uv run modal deploy docker/modal-music-gen/app.py    # Modal

快速参考

# Basic generation (uses acemusic XL Turbo by default)
uv run tools/music_gen.py --prompt "Upbeat tech corporate" --duration 60 --output bg.mp3

# Generate 4 variations, pick the best
uv run tools/music_gen.py --prompt "Calm ambient piano" --duration 30 --variations 4 --output ambient.mp3

# Fast mode (disable thinking)
uv run tools/music_gen.py --no-thinking --prompt "Quick draft" --duration 30 --output draft.mp3

# With musical control
uv run tools/music_gen.py --prompt "Calm ambient piano" --duration 30 --bpm 72 --key "D Major" --output ambient.mp3

# Scene presets (video production)
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3
uv run tools/music_gen.py --preset tension --duration 20 --output problem.mp3
uv run tools/music_gen.py --preset cta --brand digital-samba --duration 15 --output cta.mp3

# Vocals with lyrics
uv run tools/music_gen.py --prompt "Indie pop jingle" --lyrics "[verse]\nBuild it better\nShip it faster" --duration 30 --output jingle.mp3

# Cover / style transfer
uv run tools/music_gen.py --cover --reference theme.mp3 --prompt "Jazz piano version" --duration 60 --output jazz_cover.mp3

# Repaint a weak section
uv run tools/music_gen.py --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3

# Continue from existing audio
uv run tools/music_gen.py --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3

# Stem extraction
uv run tools/music_gen.py --extract vocals --input mixed.mp3 --output vocals.mp3

# Fall back to self-hosted
uv run tools/music_gen.py --cloud modal --prompt "Background music" --duration 60 --output bg.mp3

修复“千篇一律”的输出

如果生成的音乐听起来重复或缺乏变化，请按以下顺序尝试：

1. 使用 acemusic 云服务（默认）— XL Turbo 4B 加上 5Hz LM；Modal 运行相同的 XL Turbo DiT，但不含 LM；RunPod 仍使用 2B
2. 保持思考模式开启（acemusic 默认）— 5Hz LM 会将简略提示词扩展为详细的音乐描述
3. 生成多个版本 — --variations 4 会生成 4 个版本，选出最佳效果
4. 使用随机推理 — --infer-method sde 可增加随机性（相同种子也会生成不同结果）
5. 在不同场景中改变 BPM 和调性 — 不要在每个场景中都使用相同的预设
6. 使用更简洁的提示词 — 与过于详细的描述相比，“欢快的独立摇滚”能给模型更多创作自由
7. 更换种子 — 省略 --seed，让每次生成都独一无二

创建歌曲（分步指南）

1. 纯音乐背景曲（最简单）

uv run tools/music_gen.py --prompt "Upbeat indie rock, driving drums, jangly guitar" --duration 60 --bpm 120 --key "G Major" --output track.mp3

2. 带人声和歌词的歌曲

将歌词写入临时文件，或直接以内联方式传入。使用结构标签控制歌曲段落。

# Write lyrics to a file first (recommended for longer songs)
cat > /tmp/lyrics.txt << 'LYRICS'
[Verse 1]
Walking through the morning light
Coffee in my hand feels right
Another day to build and dream
Nothing's ever what it seems

[Chorus - anthemic]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Verse 2]
Screens are glowing late at night
Shipping code until it's right
The deadline's close but so are we
Almost there, just wait and see

[Chorus - bigger]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Outro - fade]
(Moving forward...)
LYRICS

# Generate the song
uv run tools/music_gen.py \
  --prompt "Upbeat indie rock anthem, male vocal, driving drums, electric guitar, studio polish" \
  --lyrics "$(cat /tmp/lyrics.txt)" \
  --duration 60 \
  --bpm 128 \
  --key "G Major" \
  --output my_song.mp3

3. 重绘效果较弱的部分

如果副歌听起来效果不佳，只需重新生成该部分：

uv run tools/music_gen.py --repaint --input my_song.mp3 --repaint-start 20 --repaint-end 35 --prompt "Powerful anthemic chorus, big drums" --output fixed.mp3

4. 续写／延长音轨

uv run tools/music_gen.py --continuation --input my_song.mp3 --prompt "Continue with gentle acoustic outro" --output extended.mp3

获得良好效果的关键提示

• 说明文字 = 整体风格（流派、乐器、情绪、制作质量）
• 歌词 = 时间结构（主歌／副歌走向、人声演绎）
• 歌词中使用大写字母 = 更强的人声力度
• 圆括号 = 和声：“We rise (together)”
• 每行保持 6–10 个音节，节奏会更自然
• 不要在说明文字中描述旋律 — 描述声音和感受
• 使用 --seed，在迭代调整提示词／歌词时锁定随机性

控制人声性别

模型通常无法仅凭“女声”或“男声”稳定地遵循要求。请同时使用以下两种方式：

1. 在提示词中：明确说明，例如“独唱女歌手，女中音”或“仅女歌手演唱，气声、亲密的嗓音”。添加歌手参考会有所帮助（例如“Brandi Carlile 风格”）。
2. 在歌词中：在每个段落前添加 [female vocal] 标签：

[female vocal]
[Verse 1]
Walking through the morning light...

[female vocal]
[Chorus - anthemic]
WE KEEP MOVING FORWARD...

仅在提示词中写“女声”通常会被忽略。提示词与歌词标签结合使用才有效。

二重唱与人声交替演唱

要让男女声在二重唱中交替演唱主歌，请同时使用提示词和逐段歌词标签：

• 提示词：“二重唱，男女声交替演唱主歌，副歌部分采用温暖和声”
• 歌词：为每个段落标注演唱者：

[Verse 1 - male vocal, storytelling]
First verse lyrics here...

[Chorus - male and female duet, harmonies]
Chorus lyrics here...

[Verse 2 - female vocal, wry]
Second verse lyrics here...

[Bridge - male vocal, spoken]
Spoken bridge...

[Bridge - female vocal, sung]
Sung response...

这样可以稳定地实现不同段落的人声交替，并在共同演唱的部分加入和声。

场景预设

预设	BPM	调性	使用场景
corporate-bg	110	C 大调	专业背景音乐、演示文稿
upbeat-tech	128	G 大调	产品发布、科技演示
ambient	72	D 大调	概览幻灯片、反思性内容
dramatic	90	D 小调	揭晓、公告
tension	85	A 小调	问题陈述、挑战
hopeful	120	C 大调	解决方案揭晓、问题解决
cta	135	E 大调	行动号召、收尾氛围
lofi	85	F 大调	屏幕录制、编码演示

任务类型

text2music（默认）

根据文本提示词和可选歌词生成音乐。

cover

从参考音频迁移风格。使用 --cover-strength（0.0-1.0）控制混合程度：

• 0.2 — 宽松地借鉴风格（创作自由度更高）
• 0.5 — 平衡的风格迁移
• 0.7 — 接近原始结构（默认值）
• 1.0 — 最大程度忠实于源音频

extract

分离音轨——从混音音频中提取单独的音轨。 音轨：vocals、drums、bass、guitar、piano、keyboard、strings、brass、woodwinds、other

上游将 extract 列为 base-model 任务（acestep-v15-base / -xl-base）。自托管端点提供的 turbo DiT（Modal 上的 XL Turbo、RunPod 上的 2B Turbo）不支持此功能，因此这些环境下的分离音轨效果可能较差。

repainting（仅限 acemusic）

重新生成现有音频中的特定时间片段，同时保留其余部分。

uv run tools/music_gen.py --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3

continuation（仅限 acemusic）

从现有音频的结尾处继续创作，以延长音频。

uv run tools/music_gen.py --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3

提示词工程

编写描述词 — 多个维度

编写描述词时，应叠加多个描述维度，而不是只用单个词语描述。

应包含的维度：

• 流派/风格：流行、摇滚、爵士、电子、lo-fi、synthwave、管弦乐
• 情绪/氛围：忧郁、欢欣、梦幻、怀旧、亲密、紧张
• 乐器：原声吉他、合成器铺底音色、808 鼓、弦乐、铜管、钢琴
• 音色：温暖、清脆、空灵、有冲击力、饱满、精致、原始
• 时代：“80 年代合成器流行乐”、“现代独立音乐”、“古典浪漫主义”
• 制作风格：lo-fi、录音室精修、现场录音、电影感
• 人声：气声、强劲、假声、沙哑、口语（或“纯音乐”）

好示例：“缓慢忧郁的钢琴叙事曲，搭配亲密的女声演唱；温暖的弦乐逐渐铺陈，最终推向强劲的副歌，录音室精修制作” 坏示例：“悲伤的歌”

核心原则

1. 具体胜于含糊——描述乐器、情绪和制作风格
2. 避免矛盾——不要同时要求“古典弦乐”和“硬核金属”
3. 重复可强调优先级——重复重要元素以突出强调
4. 描述词越简略，创作自由度越高——详细的描述词会限制模型
5. 使用元数据参数指定 BPM/调性——不要在描述词中写“120 BPM”，而应使用 --bpm 120

歌词格式

结构标签（写在歌词中，而非描述词中）：

[Intro]
[Verse]
[Chorus]
[Bridge]
[Outro]
[Instrumental]
[Guitar Solo]
[Build]
[Drop]
[Breakdown]

人声控制（添加在行或段落前）：

[raspy vocal]
[whispered]
[falsetto]
[powerful belting]
[harmonies]
[ad-lib]

能量指示：

• 全大写 = 高强度（“WE RISE ABOVE”）
• 括号 = 背景人声（“We rise (together)”）
• 每段中的每行保持 6-10 个音节，以形成自然节奏

视频制作集成

不同场景类型的配乐

场景	预设	时长	备注
标题	dramatic 或 ambient	3-5s	简短，用于营造氛围
问题	tension	10-15s	黑暗、不安
解决方案	hopeful	10-15s	宽慰、乐观
演示	lofi 或 corporate-bg	30-120s	不分散注意力，与演示时长匹配
数据统计	upbeat-tech	8-12s	逐步建立可信度
CTA	cta	5-10s	能量十足、干脆有力
片尾字幕	ambient	5-10s	柔和渐弱淡出

时间安排工作流

1. 先规划各场景时长（根据旁白脚本）
2. 生成匹配的音乐：--duration <scene_seconds>
3. 音乐时长精确（与请求时长相差不超过 0.1s）
4. 如果背景音乐要贯穿多个场景：生成一首长曲

与旁白混合

在 Remotion 中，背景音乐的混音音量应设为 10-20%：

<Audio src={staticFile('voiceover.mp3')} volume={1} />
<Audio src={staticFile('bg-music.mp3')} volume={0.15} />

旁白下方的配乐：使用纯音乐预设（corporate-bg、ambient、lofi）。 以音乐为主的场景（标题、CTA）：可以使用更高音量或带人声的音轨。

品牌一致性

使用 --brand <name> 从 brands/<name>/brand.json 加载提示。 使用 --cover --reference brand_theme.mp3 创建品牌声音标识的变体。 要让项目中的声音保持一致：固定随机种子（--seed 42），只改变时长/描述词。

高级参数

Flag	Default	Description
--thinking	on (acemusic)	5Hz LM 增强提示词并生成音频编码
--no-thinking	-	更快生成，跳过 LM 推理
--variations N	1	生成 N 个变体（1-8，仅 acemusic）
--guidance-scale	7.0	提示词遵循度（1.0-15.0）
--infer-method	ode	ode（确定性）或 sde（随机性，变化更多）
--seed	random	固定随机性以便复现

技术详情

• acemusic 云端：XL Turbo 4B DiT + 4B LM，品质最佳，每次生成约需 5-15 秒
• Modal：XL Turbo 4B DiT（ACE-Step-1.5 v0.1.8），无 LM，使用 shift 3.0 时执行 8 步（上游推荐的 Turbo 设置；可在请求中通过 shift 覆盖），启用 DCW 采样器。生成 10 秒音频时，热启动约需 4 秒，冷启动约需 50 秒
• RunPod：标准 Turbo 2B DiT，无 LM，每次生成约需 2-3 秒
• 输出：48kHz MP3/WAV/FLAC
• 时长范围：10-600 秒
• BPM 范围：30-300

不适合使用 ACE-Step 的情况

• 克隆声音——改用 Qwen3-TTS 或 ElevenLabs
• 音效——使用 ElevenLabs SFX（tools/sfx.py）
• 语音/旁白——使用配音工具，而非音乐生成工具
• 从视频中提取音轨——先使用 FFmpeg 提取音频，再使用 --extract