背景音樂
根據文字簡介,在完全離線的環境下,為 Reels 和展示影片生成原創、免版稅的純音樂。此包裝器驅動 ACE-Step 1.5(音樂模型);您(模型)將簡介塑造成良好的提示詞,生成幾個候選音檔,讓使用者挑選,並可選擇性地將獲選者混合到旁白之下。
與 voice-clone-narration 技能搭配使用:在那裡生成語音旁白,在這裡生成音樂,然後使用 mix_voiceover.sh 讓音樂在旁白下自動降低音量,製作出完成的 Reel 音訊軌道。
flowchart LR
Brief["簡介: 曲風, 情緒, bpm, 長度"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), 純音樂"]
Gen --> Mp3["候選 mp3"]
Nar["narration.mp3 (選擇性)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg sidechain 壓縮"]
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 匿名下載一次,無需 token)。如果您拉取更大的模型變體,請預留更多空間。
- 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:確定簡介
音樂品質取決於具體的提示詞。向使用者取得以下資訊(或自行推斷並說明您的選擇):
- 曲風/風格:lo-fi hip hop、電影管弦樂、商業環境音樂、合成器浪潮、民謠、活潑流行樂...
- 情緒:平靜、振奮、緊張、夢幻、有活力、憂鬱。
- 速度:慢 / 中 / 快,或明確的 BPM(例如 90)。
- 長度:秒數(10-600;Reels 通常在 30-120 秒)。
- 主要樂器(選擇性):Rhodes 鋼琴、溫暖的 Pad、柔和的鼓聲、尼龍弦吉他。
步驟 3:生成
"$PY" "$SKILL_DIR/scripts/generate_music.py" \
--prompt "溫暖 lo-fi hip hop,柔和的 Rhodes 鋼琴,輕微的 vinyl 爆裂聲,悠閒的鼓聲,可循環,純音樂" \
--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
每當有人聲說話時,音樂會自動降低音量(sidechain 壓縮),然後在間隙中恢復。音樂會被循環以覆蓋整個旁白,並有淡入淡出效果。可使用 --music-gain(背景音量,預設 -8 dB)、--duck(壓縮強度,預設 8)和 --fade 進行調整。
步驟 6:交付
嵌入或連結所選的 mp3。生成的檔案會保留在 ~/.bg-music/out/ 之下。
主要選項 (generate_music.py)
| 選項 | 預設值 | 用途 |
|---|---|---|
--prompt | (必要) | 音樂描述:曲風、情緒、樂器、氛圍。 |
--duration | 60 | 長度(秒,10-600)。 |
--bpm | 自動 | 速度(BPM,30-300);省略則讓模型選擇。 |
--count | 2 | 要生成多少個變體。 |
--out | out/music-<時間戳>.mp3 | 輸出路徑(當 --count > 1 時作為前綴)。 |
--seed | 隨機 | 固定種子以確保可重現性。 |
--keyscale | 自動 | 音樂調性,例如 "A minor"。 |
--vocals | 關閉(純音樂) | 允許人聲(背景音樂很少需要)。 |
--steps | 8 | 擴散步數(turbo 預設;更多 = 更慢,邊際改善)。 |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a(0=最佳..9=最小)。 |
--keep-wav | 關閉 | 保留中間的 wav 檔案。 |
主要選項 (mix_voiceover.sh)
| 選項 | 預設值 | 用途 |
|---|---|---|
--voice | (必要) | 旁白 mp3/wav(維持原始音量)。 |
--music | (必要) | 背景音樂 mp3/wav(會被壓低音量並循環以覆蓋旁白)。 |
--out | (必要) | 輸出混音後的 mp3。 |
--music-gain | -8 | 基準音樂音量(dB);越低表示背景越安靜。 |
--duck | 8 | 壓縮強度(壓縮器比率);越高表示音樂在語音下降低得越多。 |
--fade | 2 | 音樂淡入淡出秒數。 |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a。 |
安全性
- 在平台或情境要求時,揭露 AI 生成的音樂。
- 商業使用: ACE-Step 1.5 採用 MIT 授權,並使用已授權 / 免版稅 / 合成資料訓練,因此生成的音軌大致可安全使用。但根據模型本身的免責聲明,請避免使用複製特定藝人或特定歌曲的提示詞,並在商業發布前驗證原創性。
- 絕不將簡介、提示詞或生成的音訊上傳至任何外部服務。所有內容都保留在本機的
~/.bg-music/之下。
反模式
- 模糊的一個詞提示詞("音樂"、"酷的東西") – 您會得到泛泛的輸出。請提供曲風 + 情緒 + 樂器 + 速度。
- 在您只需要背景音樂時要求人聲 – 保持純音樂(預設值),這樣才能乾淨地襯在旁白下。
- 只生成一次就交件 – 生成
--count 2並讓使用者挑選。 - 手動將音樂疊在語音旁白下 – 使用
mix_voiceover.sh,這樣音樂會在語音下自動降低音量。 - 提示詞要求 "一首聽起來完全像 <藝人/曲目> 的歌" – 有原創性和授權風險。
- 將
~/.bg-music/中的任何內容提交到儲存庫。
資源
- 模型 zoo(為什麼在 16 GB 上使用 2B-turbo)、完整參數速查表、依情緒分類的提示詞模式、授權理由和問題排除:REFERENCE.md
- 生成用於混音的旁白:voice-clone-narration 技能。
- 在影片中驗證最終音訊:review-mp4 技能。