Communitygithub.com

haoyiyin/text-to-bgm

AIエージェントスキル:テキスト記述からBGMを生成、Apple Silicon Macで完全ローカル動作

text-to-bgm とは?

このスキルは、Apple Silicon搭載Mac上で、テキスト記述からバックグラウンドミュージック(BGM)を100%ローカルかつオフラインで生成するAIエージェント機能です。Meta社のMusicGenをAppleのMLXフレームワークに移植した「mlx-audiocraft」を基盤としており、モデルダウンロード後はインターネット不要で完全プライベートに動作します。M1/M2/M3/M4チップのGPUアクセラレーションにより高速生成が可能で、小規模モデルなら8GB RAMでも動作します。コマンドラインまたはPython APIから利用でき、ジャンル、ムード、楽器、長さなどを細かく指定して、ループ用BGMからシネマティックなサウンドトラックまで幅広く生成できます。プロンプトエンジニアリングのガイドも付属しており、AIエージェントはユーザーの要望に応じて適切なモデルやパラメータを選択し、生成結果を提供します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add haoyiyin/text-to-bgm

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

text-to-bgm は何をしますか?

テキスト記述からBGMを生成します。Apple Silicon搭載Mac上で、ローカルAIを使用。mlx-audiocraft(MetaのMusicGenをAppleのMLXフレームワークに移植したもの)を搭載。

  • 100%オフライン — モデルダウンロード後はクラウド不要、APIキー不要、インターネット不要
  • プライベート — すべての生成は端末上で実行
  • 高速 — M1/M2/M3/M4上でMLX GPUアクセラレーション対応

使用すべき場面

ユーザーが以下を依頼した場合にこのスキルを使用します:

  • BGM / インストゥルメンタル音楽の生成
  • アンビエント音楽、ローファイビート、シネマティックサウンドトラックの作成
  • 動画、ゲーム、ポッドキャスト、学習/集中セッション用のオーディオ制作
  • macOS Apple Siliconでのテキスト→音楽リクエスト全般

以下の場合は使用しないでください:

  • 効果音 → audiogen-mlx(mlx-audiocraftに含まれています)を使用
  • ボーカル/歌唱 → MusicGenはボーカルが苦手
  • 本格的な楽曲制作 → より長く構造化された音楽にはACE-Stepを検討

必要条件

  • macOS(Apple Silicon搭載:M1、M2、M3、M4)
  • Python 3.10以上(3.11推奨)
  • RAM: 小モデルで最低8GB、大規模モデルでは16GB以上
  • ディスク: モデルごとに1.2GB(小)〜約6.5GB(ステレオ大)

インストール

# 一行インストール
pip install mlx-audiocraft

# 確認
musicgen-mlx --help

または付属のセットアップスクリプトを使用:

bash setup.sh

使用方法

基本

musicgen-mlx "柔らかなピアノを使ったローファイな勉強用チルビート" -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-small300M / 1.2GB良好リアルタイム比1.3倍デフォルト推奨
facebook/musicgen-medium1.5B / 3.4GBより良いリアルタイム比約0.6倍高品質
facebook/musicgen-large3.3B / 5.5GB最高(モノラル)リアルタイム比約0.4倍高品質出力
facebook/musicgen-stereo-large3.3B / 6.5GB最高(ステレオ)リアルタイム比約0.3倍最終出力

生成パラメータ

パラメータ範囲効果
--temperature0.5–1.5高いほどクリエイティブ/多様。低いほど予測可能
--top-k100–500高いほど多様なノート選択
--cfg-coef1.0–7.0高いほどプロンプトに厳密に従う。デフォルト3.0でバランス

ラッパースクリプトの使用

便利なgenerate_bgm.shを使用:

bash generate_bgm.sh "シネマティックなオーケストラの壮大な予告編音楽" -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(["滑らかなサックスと落ち着いたドラムのローファイジャズホップ"])

# 保存
wav = np.array(audio[0])  # [チャンネル数, サンプル数]
sf.write("output.wav", wav.T, mg.sample_rate)

プロンプトエンジニアリング

包括的なガイドと例についてはprompts.mdを参照してください。

クイックヒント:

  • ジャンル/スタイルから始める:「ローファイヒップホップ」「シネマティックオーケストラ」「アンビエントエレクトロニック」
  • 楽器を追加:「温かみのあるピアノ」「柔らかなシンセパッド」「アコースティックギター」
  • ムード/雰囲気を記述:「リラックス」「高揚感」「神秘的」「エネルギッシュ」
  • 制作上の特徴を含める:「ビニールのパチパチ音」「リバーブ」「80 BPM」「サイドチェインコンプレッション」
  • 目的で締めくくる:「勉強に最適」「ポッドキャストの背景」「ゲームメニュー音楽」

⚠️ MusicGenは英語のプロンプトとインストゥルメンタル音楽で最も効果的です。

手順(AIエージェント向け)

  1. インストール確認: musicgen-mlx --helpを実行。不足している場合はpip install mlx-audiocraftでインストール。
  2. 要件の収集: ユーザーにジャンル、ムード、長さを尋ねる。曖昧な場合は人気のBGMスタイルを提案。
  3. モデル選択: デフォルトはfacebook/musicgen-small(高速、300M)。より高品質にはfacebook/musicgen-medium、最高品質にはfacebook/musicgen-stereo-largeを使用。
  4. プロンプト作成: prompts.mdのプロンプトガイドに従い、10〜30語の英語記述を作成。
  5. 長さの設定: ループには15〜30秒、短いBGMには30〜60秒、長めの楽曲には60〜120秒。
  6. 生成: musicgen-mlx "<プロンプト>" -m <モデル> -d <秒> -o <パス>.wavを実行。
  7. 報告: ユーザーに出力ファイルパスを伝える。必要に応じてパラメータ調整後の再生成を提案。

注意点

  • ⚠️ 初回実行時にモデルをダウンロード — HuggingFaceから1.2〜6.5GB。ユーザーに警告すること。
  • ⚠️ Apple Siliconのみ — Intel Macでは動作しません。
  • ⚠️ デフォルトは8秒 — BGMでは必ず-dを指定。
  • ⚠️ インストゥルメンタル専用 — ボーカル/歌詞は苦手。
  • ⚠️ 非商用ライセンス — CC-BY-NC 4.0。商用利用は不可。
  • ⚠️ RAM消費大 — 8GBマシンでは小規模・中規模モデルのみ使用。
  • ⚠️ 大規模モデルは遅い — ステレオ大はリアルタイム比約0.3倍。60秒の生成に約3分かかる。

動作確認

# 1. CLIの確認
musicgen-mlx --help

# 2. 簡単なテスト
musicgen-mlx "ピアノメロディー" -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ジャンルテンプレート付きプロンプトエンジニアリングガイド

関連スキル