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（小）至 ~6.5 GB（立體聲大）
安裝
# 一行安裝
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 取樣 top-k（預設：250）
--temperature T 取樣溫度（預設：1.0）
--cfg-coef C 分類器自由引導係數（預設：3.0）
模型
| 模型 | 大小 | 品質 | 速度（M4 Max） | 使用案例 |
|---|---|---|---|---|
facebook/musicgen-small | 300M / 1.2GB | 良好 | 1.3x 即時 | 預設選擇 |
facebook/musicgen-medium | 1.5B / 3.4GB | 較佳 | ~0.6x 即時 | 較佳品質 |
facebook/musicgen-large | 3.3B / 5.5GB | 最佳（單聲道） | ~0.4x 即時 | 高品質 |
facebook/musicgen-stereo-large | 3.3B / 6.5GB | 最佳（立體聲） | ~0.3x 即時 | 最終輸出 |
生成參數
| 參數 | 範圍 | 效果 |
|---|---|---|
--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 代理）
- 檢查安裝：執行
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 模型。
- ⚠️ 大型模型速度慢 — 立體聲大模型約為即時的 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 | 易於代理使用的包裝生成腳本 |
prompts.md | 提示工程指南，含類型模板 |