text-to-bgm 是做什么的？
在 Apple Silicon Mac 上使用本地 AI 根据文本描述生成背景音乐 (BGM)。由 mlx-audiocraft 驱动 — Meta 的 MusicGen 移植到 Apple 的 MLX 框架。
- 100% 离线 — 无需云服务，无需 API 密钥，模型下载后无需网络连接
- 隐私保护 — 所有生成过程均在设备上完成
- 快速 — 在 M1/M2/M3/M4 上使用 MLX GPU 加速
何时使用
当用户要求时使用此技能：
- 生成背景音乐 / BGM / 器乐
- 创建环境音乐、lo-fi 节拍、电影配乐
- 为视频、游戏、播客或学习/专注时段制作音频
- 在 macOS Apple Silicon 上进行任何文本到音乐请求
请勿用于：
- 音效 → 使用
audiogen-mlx（包含在 mlx-audiocraft 中） - 人声/演唱 → MusicGen 在人声方面表现不佳
- 完整制作歌曲 → 考虑使用 ACE-Step 生成更长的结构化音乐
要求
- macOS 且配备 Apple Silicon (M1, M2, M3, M4)
- Python 3.10+（推荐 3.11）
- 内存：小模型最低 8 GB，大模型需要 16 GB+
- 磁盘：每个模型 1.2 GB（small）至 ~6.5 GB（stereo-large）
安装
# 一行安装
pip install mlx-audiocraft
# 验证
musicgen-mlx --help
或者使用附带的安装脚本：
bash setup.sh
使用
基础用法
musicgen-mlx "lo-fi chill study beats with soft piano" -d 30 -o bgm.wav
完整 CLI 参考
musicgen-mlx [-h] [-m MODEL] [-o FILE] [-d SEC] [--no-open]
[--top-k K] [--temperature T] [--cfg-coef C]
prompt
参数：
prompt 音乐文本描述
选项：
-m, --model NAME HuggingFace 模型（默认：facebook/musicgen-small）
-o, --output FILE 输出 WAV 路径（默认：./musicgen_output.wav）
-d, --duration SEC 持续时间（秒）（默认：8）
--no-open 生成后不打开文件
--top-k K 顶部 k 采样（默认：250）
--temperature T 采样温度（默认：1.0）
--cfg-coef C 无分类器引导系数（默认：3.0）
模型
| 模型 | 大小 | 质量 | 速度 (M4 Max) | 用例 |
|---|---|---|---|---|
facebook/musicgen-small | 300M / 1.2GB | 良好 | 1.3 倍实时 | 默认选择 |
facebook/musicgen-medium | 1.5B / 3.4GB | 较好 | ~0.6 倍实时 | 更高品质 |
facebook/musicgen-large | 3.3B / 5.5GB | 最佳（单声道） | ~0.4 倍实时 | 高品质 |
facebook/musicgen-stereo-large | 3.3B / 6.5GB | 最佳（立体声） | ~0.3 倍实时 | 最终输出 |
生成参数
| 参数 | 范围 | 效果 |
|---|---|---|
--temperature | 0.5–1.5 | 越高 = 越有创意/多变。越低 = 越可预测 |
--top-k | 100–500 | 越高 = 音符选择越多样 |
--cfg-coef | 1.0–7.0 | 越高 = 与提示词契合越严格。默认 3.0 较为平衡 |
使用包装脚本
为方便起见，请使用 generate_bgm.sh：
bash generate_bgm.sh "cinematic orchestral epic trailer music" -d 45
选项：-m <模型>、-d <秒数>、-t <温度>、-o <输出>
Python API
import mlx.core as mx
import numpy as np
import soundfile as sf
from audiocraft_mlx.models.musicgen import MusicGen
# 加载模型
mg = MusicGen.get_pretrained("facebook/musicgen-small")
# 设置生成参数
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)
# 生成
audio = mg.generate(["lo-fi jazz hop with smooth saxophone and chill drums"])
# 保存
wav = np.array(audio[0]) # [通道, 采样]
sf.write("output.wav", wav.T, mg.sample_rate)
提示词工程
请参阅 prompts.md 获取包含示例的全面指南。
快速提示：
- 以流派/风格开头："lo-fi hip hop"、"cinematic orchestral"、"ambient electronic"
- 添加乐器："warm piano"、"soft synth pads"、"acoustic guitar"
- 描述情绪/氛围："relaxing"、"uplifting"、"mysterious"、"energetic"
- 包含制作特性："vinyl crackle"、"reverb"、"80 BPM"、"sidechain compression"
- 以用途结尾："perfect for study"、"background for podcast"、"game menu music"
⚠️ MusicGen 对英文提示词和器乐效果最佳。
操作流程（面向 AI Agent）
- 检查安装：运行
musicgen-mlx --help。如果缺失，通过pip install mlx-audiocraft安装。 - 收集需求：询问用户关于流派、情绪、时长。如果模糊，建议流行的 BGM 风格。
- 选择模型：默认使用
facebook/musicgen-small（快速，300M）。使用facebook/musicgen-medium获取更好的质量，或使用facebook/musicgen-stereo-large获取最佳效果。 - 撰写提示词：按照 prompts.md 中的提示指南，构建一个 10–30 词的英文描述。
- 设置时长：循环片段 15–30 秒，短 BGM 30–60 秒，较长片段 60–120 秒。
- 生成：运行
musicgen-mlx "<提示词>" -m <模型> -d <秒> -o <路径>.wav - 报告：告知用户输出文件路径。如有需要，可提供调整参数后重新生成的选项。
注意事项
- ⚠️ 首次运行会下载模型 — 从 HuggingFace 下载 1.2–6.5 GB。请提醒用户。
- ⚠️ 仅限 Apple Silicon — 不适用于 Intel Mac。
- ⚠️ 默认 8 秒时长 — 对于 BGM，务必指定
-d。 - ⚠️ 仅器乐 — 在人声/歌词方面表现不佳。
- ⚠️ 非商业许可 — CC-BY-NC 4.0。不可用于商业用途。
- ⚠️ 内存占用高 — 8GB 机器应仅使用 small/medium 模型。
- ⚠️ 大模型速度慢 — stereo-large 约 0.3 倍实时。生成 60 秒大约需要 3 分钟。
验证
# 1. 检查 CLI
musicgen-mlx --help
# 2. 快速测试
musicgen-mlx "piano melody" -d 5 -o /tmp/test_bgm.wav
# 3. 验证输出
file /tmp/test_bgm.wav
# 预期输出：RIFF (little-endian) data, WAVE audio
# 4. 收听
open /tmp/test_bgm.wav
文件
| 文件 | 用途 |
|---|---|
SKILL.md | 本文件 — 技能定义与参考 |
setup.sh | 一键安装脚本 |
generate_bgm.sh | 便于 Agent 友好使用的包装脚本 |
prompts.md | 含流派模板的提示词工程指南 |