Communitygithub.com

背景音樂生成

本地優先的 AI 編碼代理技能 — 100% 在您的機器上執行,無需雲端或 API 金鑰。支援 Apple Silicon (MLX/Metal):從文字簡介生成免版稅的背景音樂。

背景音樂生成 是什麼?

這個技能讓 AI 編碼代理(例如 Cursor 或 Claude Code)能夠根據使用者提供的文字簡介,在本機上生成原創、免版稅的背景音樂,無需網路連線(首次設定除外)。它驅動 ACE-Step 1.5 音樂模型,透過 MLX 框架在 Apple Silicon Mac 上獲得最佳效能,但如果需要也會回退至 PyTorch。工作流程包含引導使用者確認曲風、情緒、BPM 和長度,產生多個候選音檔,讓使用者挑選,還能選擇性地將選中的音樂與旁白混音(利用 `mix_voiceover.sh` 實現 sidechain 壓縮,讓音樂在說話時自動降低音量)。這個技能特別適合為 Reels 或展示影片創建配樂,並能與同一個生態系中的「語音複製旁白」技能順暢搭配。所有生成的檔案都安全地儲存在 `~/.bg-music/` 目錄下,確保隱私與在地化。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

背景音樂

根據文字簡介,在完全離線的環境下,為 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(必要)音樂描述:曲風、情緒、樂器、氛圍。
--duration60長度(秒,10-600)。
--bpm自動速度(BPM,30-300);省略則讓模型選擇。
--count2要生成多少個變體。
--outout/music-<時間戳>.mp3輸出路徑(當 --count > 1 時作為前綴)。
--seed隨機固定種子以確保可重現性。
--keyscale自動音樂調性,例如 "A minor"。
--vocals關閉(純音樂)允許人聲(背景音樂很少需要)。
--steps8擴散步數(turbo 預設;更多 = 更慢,邊際改善)。
--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/ 中的任何內容提交到儲存庫。

資源

  • 模型 zoo(為什麼在 16 GB 上使用 2B-turbo)、完整參數速查表、依情緒分類的提示詞模式、授權理由和問題排除:REFERENCE.md
  • 生成用於混音的旁白:voice-clone-narration 技能。
  • 在影片中驗證最終音訊:review-mp4 技能。

相關技能