Communitygithub.com

背景音乐生成(客户端本地)

在本地 Apple Silicon Mac 上,完全离线生成免版税的纯器乐背景音乐,支持文本简报驱动,并可与旁白自动混合。

背景音乐生成(客户端本地) 是什么?

这是一个为 Cursor 等 AI 编程代理设计的本地优先技能,专注于生成原创、免版税的器乐背景音乐。它利用 ACE-Step 1.5 音乐模型(通过 MLX/Metal 加速)在本地离线运行,无需任何云端服务或 API 密钥。用户只需提供关于风格、情绪、节奏和时长的简短描述(Brief),AI 代理会自动优化提示词、生成多个候选音频,并让用户选择最佳版本。它还提供了与旁白克隆技能配合使用的音频混合功能,通过 ffmpeg 侧链压缩自动降低音乐音量以衬托旁白。所有生成的文件和模型权重都存储在用户目录的 `~/.bg-music/` 下,确保数据完全保留在本地。技能支持 Apple Silicon Mac,需要大约 10GB 磁盘空间和 `uv`、`git`、`ffmpeg` 等工具。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

背景音乐生成

根据一段文本简报,在完全离线的环境下生成适用于短视频和演示视频的原创免版税器乐音乐。本技能实际调用 ACE-Step 1.5(音乐模型);你(AI 代理)负责将简报转化为优秀的提示词,生成几个候选作品,让用户挑选,并可选择将胜出的音乐与旁白混合。

与 voice-clone-narration 配合使用:在那里生成旁白,在这里生成音乐,然后通过 mix_voiceover.sh 在旁白播出时自动降低音乐音量,制作出完整的短视频音频轨道。

flowchart LR
  Brief["brief: genre, mood, bpm, duration"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
  Gen --> Mp3["candidate mp3s"]
  Nar["narration.mp3 (optional)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg sidechain ducking"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

所有代码和数据都保存在 仓库外部 的 ~/.bg-music/ 目录下(包括 ACE-Step 的代码、模型权重和生成的音频)。

前提条件

  • uv(包管理器)和 git —— 该模型是一个 uv sync 应用,不是普通的 pip 安装。安装脚本会将其设置到隔离的环境中。
  • ffmpeg 可执行文件需要在 PATH 中(用于 MP3 编码和混合)。如果缺失,请暂停并让用户执行 brew install ffmpeg。
  • 约 10 GB 可用磁盘空间 用于存储代码和模型权重(从 Hugging Face 匿名下载一次,无需令牌)。如果使用更大的模型变体,需要预留更多空间。
  • Apple Silicon Mac 以获得快速原生路径(MLX)。在 CUDA/CPU 上会回退到 PyTorch(CPU 上较慢)。16 GB 统一内存足以运行默认的 2B-turbo + 0.6B-LM 等级。
  • 仅在首次运行时需要联网(用来拉取代码和权重)。生成过程完全离线。

设置

解析技能目录并运行一次设置脚本(会克隆 ACE-Step 1.5 并同步其环境——首次运行会下载依赖,可能需要几分钟):

SKILL_DIR="<本 SKILL.md 所在的文件夹路径>"   # 例如 .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

然后设置生成脚本会用到的路径(设置脚本也会输出这些信息):

BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"

工作流程

复制以下清单并跟踪进度:

- [ ] 1. 确认简报:风格、情绪、节奏(BPM)、时长、主要乐器
- [ ] 2. 设置:运行 setup_env.sh(仅首次)
- [ ] 3. 编写具体的提示词:生成 2 个候选作品
- [ ] 4. 播放/链接候选作品:让用户选择(如需要可重新生成)
- [ ] 5. (可选)将胜出的音乐与旁白 mp3 混合(带闪避效果)
- [ ] 6. 交付 mp3 文件

步骤 1:确定简报

音乐质量取决于具体的提示词。请从用户那里获取以下信息(或者自行推断并说明你的选择):

  • 风格:低保真嘻哈、电影管弦乐、企业环境、合成波、原声民谣、欢快流行……
  • 情绪:平静、振奋、紧张、梦幻、充满活力、忧郁。
  • 节奏:慢速/中速/快速,或明确的 BPM(例如 90)。
  • 时长:秒(10-600;短视频通常 30-120 秒)。
  • 主要乐器(可选):Rhodes 钢琴、温暖音垫、柔和鼓点、尼龙弦吉他。

步骤 3:生成

"$PY" "$SKILL_DIR/scripts/generate_music.py" \
  --prompt "温暖的低保真嘻哈,柔和的 Rhodes 钢琴,轻微的噼啪声,悠闲的鼓点,可循环,纯器乐" \
  --bpm 80 --duration 60 --count 2 \
  --out "$BG_HOME/out/lofi.mp3"
  • 轨道默认是 纯器乐(无演唱)。
  • --count 2 会生成两个变体供选择(lofi-1.mp3、lofi-2.mp3)。
  • 写入 MP3 文件并打印其路径和时长。首次运行会下载模型权重,后续运行会快得多。

好的提示词应该具体且用逗号分隔。包含风格 + 情绪 + 2-3 种乐器 + 节奏描述 + “纯器乐”/“可循环”。示例:

  • "电影感鼓舞人心的管弦乐,柔和的弦乐,钢琴,轻轻的打击乐渐渐升至温暖的浪潮,纯器乐"
  • "干净的企业环境音乐,柔和的合成音垫,轻快的拨弦,乐观,极简,纯器乐"
  • "强劲的合成波,模拟贝斯,复古琶音,有力的鼓点,夜间驾驶的能量感,纯器乐"

步骤 5:与旁白混合(可选)

如果用户还有旁白音频(例如来自 voice-clone-narration 技能),可以自动在旁白播出时降低音乐音量:

bash "$SKILL_DIR/scripts/mix_voiceover.sh" \
  --voice ~/.voice-clone-narration/out/test-en.mp3 \
  --music "$BG_HOME/out/lofi-1.mp3" \
  --out ~/Desktop/reel-audio.mp3

音乐会在旁白播放时自动降低音量(侧链压缩),然后在间隙恢复。它会循环播放以覆盖旁白的时长,并附带淡入淡出效果。可以通过 --music-gain(背景音量,默认 -8 dB)、--duck(闪避强度,默认 8)和 --fade 进行微调。

步骤 6:交付

嵌入或链接所选的 mp3 文件。生成的文件保存在 ~/.bg-music/out/ 目录下。

关键选项(generate_music.py)

选项默认值用途
--prompt(必需)音乐描述:风格、情绪、乐器、氛围。
--duration60时长(秒),范围 10-600。
--bpm自动节奏(BPM),范围 30-300;留空让模型自动选择。
--count2生成多少个变体。
--outout/music-<时间戳>.mp3输出路径(当 --count > 1 时可作为前缀)。
--seed随机固定随机种子以保证可复现性。
--keyscale自动音乐调性,例如 "A minor"。
--vocals关闭(纯器乐)允许人声(背景音乐通常不需要)。
--steps8扩散步数(快速默认值;步数越多速度越慢,效果略有提升)。
--mp3-quality2ffmpeg 的 libmp3lame -q:a 参数(0=最佳..9=最小)。
--keep-wav关闭保留中间 WAV 文件。

关键选项(mix_voiceover.sh)

选项默认值用途
--voice(必需)旁白的 mp3/wav 文件(保持原始音量)。
--music(必需)背景音乐的 mp3/wav 文件(会被闪避并循环以覆盖旁白时长)。
--out(必需)混合后的输出 mp3 文件。
--music-gain-8背景音乐的基准音量(dB);数值越低音乐越安静。
--duck8闪避强度(压缩比);数值越高,音乐在语音期间下降得越明显。
--fade2音乐淡入/淡出的秒数。
--mp3-quality2ffmpeg 的 libmp3lame -q:a 参数。

安全注意事项

  • 在平台或上下文要求时,请声明音乐由 AI 生成。
  • 商业使用: ACE-Step 1.5 使用 MIT 许可证,训练数据基于已授权/免版税/合成数据,因此生成的曲目在商业用途上基本安全。但根据模型自身的声明,请避免使用模仿特定艺术家或曲风特征的提示词,并在商业发布前验证原创性。
  • 切勿将 简报、提示词或生成的音频上传到任何外部服务。所有数据都保留在本地 ~/.bg-music/ 目录下。

反模式

  • 使用模糊的一词提示词(“音乐”、“酷一点”)—— 你会得到平庸的输出。请提供风格 + 情绪 + 乐器 + 节奏。
  • 在只需要背景音乐时要求加入人声 —— 保持纯器乐(默认设置),这样能干净地衬托旁白。
  • 只生成一次就交付 —— 请使用 --count 2 生成多个变体并让用户选择。
  • 手动将音乐叠加到旁白下面 —— 请使用 mix_voiceover.sh,让音乐在语音期间自动闪避。
  • 提示“一首听起来和 <艺术家/曲目> 完全一样的歌” —— 存在原创性和授权风险。
  • 将 ~/.bg-music/ 中的任何内容提交到代码仓库。

参考资料

  • 模型动物园(为什么在 16GB 内存上使用 2B-turbo)、完整参数速查表、按情绪分类的提示模式、授权理由和故障排除: REFERENCE.md
  • 生成与音乐混合的旁白:请参考 voice-clone-narration 技能。
  • 在视频中验证最终音频:请参考 review-mp4 技能。

相关技能