Sonicmatch

Sonicmatch

ライセンスに配慮したBGMのための、動画ネイティブなMCP サーバーです。 台本ではなく映像を確認し、候補リスト、12～20秒のフック、ffmpegのダッキング仕様を返します。

パッケージ／CLI：sonicmatch-mcp。Claude Desktop、Cursor、CodexなどのMCP クライアント向けのModel Context Protocolサーバーです。Instagram Reel、YouTube Short、TikTok風のクリップを渡すと、各行にライセンスを明記したロイヤリティフリー／Creative Commonsの候補を取得できます。

動画からBGMを選ぶ機能はすでにあります。差別化要因は「音楽もおすすめします」ではありません。

• 台本ではなく映像を確認します
• フックの区間とffmpegのダッキング仕様を返します
• エージェントネイティブです
• ごまかさずにライセンスを明記します

カタログの品質が成否を左右します。ツールを増やしても解決しません。

Video or URL in
  → scene / mood / pace / speech analysis
  → license-safe BGM shortlist
  + beat/cut hints
  + optional mix preview

これを「台本を入力 → YouTube Musicを検索」として扱わないでください。それはすでに存在します（mcp-bgm-recommender）。Sonicmatchは動画を確認します。

自分で管理できるもの	自分で管理できないもの
ローカルファイル／公開URLの取り込み	プラットフォームの音楽ライセンス
ムード、エネルギーの変化、音声と無音、シーンの切り替わり	Meta／TikTokの「トレンド音源」グラフ
CC／ロイヤリティフリーのカタログと、オプションの有料アダプター	Spotify／Instagramの公式ライブラリ
ランク付けされたトラック、プレビューURL、ミックス仕様、ffmpeg	Instagramへの自動投稿

目指す流れ： ingest_video → analyze_video_music → recommend_bgm → preview_mix → export_mix_spec

ライセンスに関する警告（必ずお読みください）

• コードはMITライセンスです。
• トラックごとにライセンスが異なります。 おすすめの各項目にライセンスを表示します。
• ここで提供するものは、Instagram公式スタンプ、TikTok Commercial Music Libraryのトラック、YouTube Audio Library APIの結果ではありません。
• アダプターが明示的にユーザー所有のライセンス済みライブラリでない限り、商用ポップスをおすすめしないでください。
• CC-BYにはクレジット表記が必要です。CC-BY-NCは広告やショップでは使用できません。非営利向けのトラックが自動でおすすめされることはありません。
• 広告やショップ向けには、Artlist／EpidemicのJSON（examples/user_library.example.json）をユーザー所有のものとして接続してください。これらのサイトをスクレイピングしないでください。
• 適切でないソースを指定すると、Content IDに検出される可能性があります。CCの表示は免責を意味しません。

デモ

./clip.mp4を渡しました。Instagram Reel向けに分析して、インストゥルメンタルのBGMを5曲おすすめしてください。次に、最上位の候補をダッキング付きでミックスし、ffmpegのコマンドを教えてください。

このプロンプトが製品です。以下の手順でインストールし、Claude Desktop、Cursor、またはCodexに接続して、貼り付けてください。

クイックスタート

**Python 3.10+**と、PATH上のffmpeg／ffprobeが必要です。yt-dlpは任意で、デフォルトでは無効です（SONICMATCH_ALLOW_YTDLP=0）。プラットフォームのエクストラクターは動作しなくなることがあり、利用規約に違反する可能性もあるためです。ローカルファイルの使用をおすすめします。

PyPIプロジェクトはsonicmatch-mcpです。コンソールスクリプトはsonicmatch-mcpで、uvxとpipxが実行します。python -m sonicmatchも同じサーバーを起動します。最初のタグを公開するまで、PyPIバッジは空のままです。それまではgitからインストールしてください。メンテナー向けの手順：PUBLISH.md。

現在利用可能（git）

uvx --from git+https://github.com/js713-lab/sonic-match-mcp.git sonicmatch-mcp

pip install git+https://github.com/js713-lab/sonic-match-mcp.git
sonicmatch-mcp --version   # or: python -m sonicmatch --version

最初のPyPIリリース後

uvx sonicmatch-mcp
# or
pipx install sonicmatch-mcp
sonicmatch-mcp --version

クローンから（編集可能＋テスト）

git clone https://github.com/js713-lab/sonic-match-mcp.git
cd sonic-match-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # optional keys

# stdio (Claude Desktop / Cursor / Codex)
sonicmatch-mcp

# streamable HTTP (web editors). No authentication. Keep it on loopback.
sonicmatch-mcp --http --port 8765

# same clone, uv
uv venv && uv pip install -e ".[dev]"
uv run sonicmatch-mcp

pytest          # generates tiny color mp4s with ffmpeg
ruff check src tests

シードカタログには、Reel エディター向けの約 20 件の行（カフェ、製品、トーキングヘッド、旅行、料理、ファッション、イベント）に加え、ボーカル用のフィクスチャと CC-BY-NC フィクスチャが含まれています。API キーがなくても動作します。Gemini、Jamendo、Freesound は任意で、利用できない場合はツールの応答に注記を付けて機能を縮小します。シード行にホストされた音声がないのは意図的です。preview_mix がデモ用のベッドを合成します。実際の広告では、すでにライセンスを取得している JSON を SONICMATCH_LIBRARY_PATH ／ EPIDEMIC_LIBRARY_PATH ／ ARTLIST_LIBRARY_PATH に指定してください。

変数	必須	内容
GEMINI_API_KEY	いいえ	analyze_video_music 用の Gemini 動画理解
JAMENDO_CLIENT_ID	いいえ	Jamendo 検索
FREESOUND_API_KEY	いいえ	Freesound のベッドとループ
SONICMATCH_LIBRARY_PATH	いいえ	ユーザー所有のライブラリ JSON。EPIDEMIC_LIBRARY_PATH、ARTLIST_LIBRARY_PATH も指定できます
SONICMATCH_ALLOW_YTDLP	いいえ	1 にするとプラットフォーム URL の取り込みを有効化します。デフォルトは 0
SONICMATCH_MAX_DOWNLOAD_MB	いいえ	ダウンロード上限。デフォルトは 200
SONICMATCH_HTTP_HOST / SONICMATCH_HTTP_PORT	いいえ	--http のバインド先。デフォルトは 127.0.0.1:8765

機能

• 映像を確認します。 GEMINI_API_KEY を設定すると Gemini 動画理解を使用し、設定しない場合はローカルの ffmpeg ／音声ヒューリスティクス（任意で Whisper、PySceneDetect、librosa）を使用します。
• すべての行にライセンスを表示します。 CC ／ロイヤリティフリー／ユーザー所有のライブラリに対応します。非商用トラックを自動でおすすめすることはありません。生成したベッドは自動おすすめの対象外です。
• エディター向けの出力です。 12～20 秒のフックのイン／アウト、音声のダッキング、ffmpeg レシピ、CapCut ／Premiere ／DaVinci ／エージェント向けのミックス仕様を提供します。
• エージェントネイティブな MCP です。 Claude Desktop と Cursor 向けの stdio、ウェブエディター向けのストリーミング可能な HTTP に対応します。数 MB の生動画をペイロード経由で送信することはありません。代わりに asset_id を返します。
• API キーがなくても動作します。 Reels 向けの 20 トラックのシードカタログを利用できます。Jamendo、Freesound、ユーザー所有の Artlist ／Epidemic JSON は任意です。
• ビートに合わせてカットします。 suggest_cuts はシーンのカットを BPM グリッドに合わせ、EDL 形式のイントロ／ピーク／アウトロを返します。
• ブランド設定を維持します。 BPM ／ムード／ボーカルなしのキットを保存し、brand_kit=… を recommend_bgm に渡せます。
• 単発ではなくシリーズに対応します。 analyze_batch（最大 20 件）はムードをクラスタリングし、共通のミニプレイリストを返します。
• クローズドな仕組みについて誠実に扱います。 偽の「トレンド音源」、公式 IG ステッカー、Content-ID セーフの表示はありません。yt-dlp によるプラットフォーム取り込みはオプトインです。

ツール

ツール	内容
status	ffmpeg ／キー／シード件数／初日リスクゲート
ingest_video	ローカルパスまたは HTTPS URL → asset_id（動画バイト列は返しません）。プラットフォーム URL には SONICMATCH_ALLOW_YTDLP=1 が必要です
analyze_video_music	ムード、エネルギー曲線、音声、シーン、フック区間、BPM、検索クエリ
recommend_bgm	ランク付けされた 3～7 曲＋理由＋ライセンス＋フックのイン／アウト
search_music	シード＋任意のカタログを対象にしたフリーテキスト／BPM ／ムード検索
get_track	1 曲のメタデータ、ライセンス、クレジット表記、URL
preview_mix	フックのトリミング、ループ、任意のダッキング → プレビューファイル＋ffmpeg＋ミックス仕様
export_mix_spec	ミックス仕様＋ffmpeg＋クレジット表記（render=true の場合を除き、レンダリングは行いません）
suggest_cuts	ビートグリッド、グリッドに合わせたシーンカット、EDL、イントロ／ピーク／アウトロ
generate_bed	source=generated と表示されたデモ用ベッド。i_understand_not_commercially_cleared=true が必要です
save_brand_kit	recommend_bgm(brand_kit=…) 用に BPM ／ムード／ボーカルなしの設定を保存
analyze_batch	最大 20 本のクリップ → ムードクラスタ＋共通のミニプレイリスト

プロンプトテンプレートも付属します。「IG のミュージックステッカーのように、この動画を採点してください。」

製品ルール（Instagram 風であり、Instagram ではありません）

• speech_coverage > 0.25 の場合はインストゥルメンタルを優先します
• 曲全体ではなく、フック区間をおすすめします
• 理由を表示します（カット間隔は平均 0.8s、112 BPM、暖かみのあるゴールデンアワー）
• ライセンス＋クレジット表記を必ず返します
• 40 曲ではなく、3～7 曲を返します
• ユーザーはムード／ジャンル／歌詞なし／プラットフォーム／エネルギーを上書きできます
• 実際に該当する場合を除き、「Instagram 公式ステッカーで使用許諾済み」とは決して主張しません

例

プロンプト：

./clip.mp4 を置きました。Instagram Reel 向けに分析して、インストゥルメンタルの BGM を 5 曲おすすめしてください。その後、ダッキングを適用して最有力候補をミックスし、ffmpeg コマンドを教えてください。

エージェントは次の順に呼び出します。

1. ローカルパスを指定して ingest_video を呼び出します。結果は動画のバイトデータではなく、asset_id です。
2. platform_hint を instagram_reel に設定して analyze_video_music を呼び出します。
3. その asset_id と max_results を 5 に設定して recommend_bgm を呼び出します。
4. 最有力のトラックに対してダッキングを適用して preview_mix を呼び出し、その後 export_mix_spec を呼び出します。

おすすめの各行には、score、reason、suggested_in_out（フック）、ducking、license_ok_for_platform、content_id_risk（unknown または likely。cleared にはなりません）が含まれます。シードフィクスチャには seed_golden_hour_latte（CC0-1.0）と seed_indie_porch_110（CC-BY-4.0）が含まれます。ホストされた音源はありません。preview_mix はデモ用の音源を合成します。CC-BY-NC の行は検索できますが、自動的にはおすすめされません。

Claude Desktop

claude_desktop_config.json。Git から、クローンせずに使う場合：

{
  "mcpServers": {
    "sonicmatch": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/js713-lab/sonic-match-mcp.git",
        "sonicmatch-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "",
        "JAMENDO_CLIENT_ID": "",
        "FREESOUND_API_KEY": ""
      }
    }
  }
}

クローン後は、command に .venv/bin/sonicmatch-mcp の絶対パスを指定できます。PyPI リリース後は、args に ["sonicmatch-mcp"] を指定するだけです。コピーして貼り付けて使えるファイル：examples/claude_desktop.mcp.json、examples/claude_desktop.pypi.mcp.json。

Cursor

プロジェクトの .cursor/mcp.json、または ~/.cursor/mcp.json。Git から、クローンせずに使う場合 — examples/cursor.mcp.json：

{
  "mcpServers": {
    "sonicmatch": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/js713-lab/sonic-match-mcp.git",
        "sonicmatch-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "",
        "JAMENDO_CLIENT_ID": "",
        "FREESOUND_API_KEY": ""
      }
    }
  }
}

PyPI リリース後は、examples/cursor.pypi.mcp.json を使用します（args に ["sonicmatch-mcp"] を指定する uvx）。クローンから使う場合は、"command": "uv", "args": ["--directory", "/absolute/path/to/sonic-match-mcp", "run", "sonicmatch-mcp"] を指定します。pip install 後は、そのインタープリターにパッケージがインストールされていれば、"command": "python3", "args": ["-m", "sonicmatch"] が使えます。

Codex

Codex は ~/.codex/config.toml を読み込みます。同じファイルが Codex IDE 拡張機能と ChatGPT デスクトップアプリでも共有されます。現在利用できます — examples/codex.config.toml：

[mcp_servers.sonicmatch]
command = "uvx"
args = ["--from", "git+https://github.com/js713-lab/sonic-match-mcp.git", "sonicmatch-mcp"]

[mcp_servers.sonicmatch.env]
GEMINI_API_KEY = ""
JAMENDO_CLIENT_ID = ""
FREESOUND_API_KEY = ""

または CLI から：

codex mcp add sonicmatch -- uvx --from git+https://github.com/js713-lab/sonic-match-mcp.git sonicmatch-mcp

PyPI リリース後は、args は sonicmatch-mcp だけになります。そのファイルはこちらです：examples/codex.pypi.config.toml：

codex mcp add sonicmatch -- uvx sonicmatch-mcp

codex mcp list を実行すると、sonicmatch が表示されます。信頼済みのプロジェクトでは、ホームディレクトリのファイルの代わりに .codex/config.toml を使用できます。

ユーザーが所有する Epidemic／Artlist の JSON 形式：examples/user_library.example.json。レジストリのメタデータ：server.json。HTTP エディターでは、sonicmatch-mcp --http の実行後に http://127.0.0.1:8765/mcp を指定できます。

ホステッド版（sonic.codecrafter.dev）

GitHub リポジトリは MIT のままです。自分で実行しても、利用量に応じた課金はありません。

公開エンドポイントでは、ツール呼び出しごとにクレジットが課金されます。トライアルキーは 25 クレジットです。パックの価格：Reel は 500 クレジット／$9、Studio は 3000 クレジット／$39。ホスト上では、まだカード決済に接続されていません。

ランディングページは https://sonic.codecrafter.dev です。自分の映像を使わずにマッチを試すには、ページ上で サンプルクリップを使う を選ぶか、examples/sample-clip.mp4 をダウンロードしてアップロードします。

1. https://sonic.codecrafter.dev を開き、トライアルキーを取得します（または有料キーを使用します）。
2. export SONICMATCH_API_KEY=sm_…
3. Cursor に追加します。ページ上のボタンを使うか、examples/cursor.hosted.mcp.json を ~/.cursor/mcp.json に貼り付けます。

{
  "mcpServers": {
    "sonicmatch": {
      "url": "https://sonic.codecrafter.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SONICMATCH_API_KEY}"
      }
    }
  }
}

--http には認証がありません。ループバック上でのみ使用してください。Docker イメージはコンテナのポートを使用できるように 0.0.0.0 にバインドします。このポートをインターネットに公開しないでください。SECURITY.md を参照してください。

アーキテクチャ

flowchart TB
  subgraph mcp [MCP Server - FastMCP / Python - stdio + HTTP]
    tools[ingest_video / analyze_video_music / recommend_bgm / preview_mix / export_mix_spec / suggest_cuts]
  end
  tools --> ingest
  tools --> brain
  tools --> hub
  tools --> mixer
  ingest[Ingestor<br/>yt-dlp · ffmpeg · ffprobe · URL/file]
  brain[Video Brain<br/>Gemini / local VL · librosa · PySceneDetect · Whisper]
  hub[Music Hub<br/>seed CC · Jamendo · Freesound · user library · generate]
  mixer[Mixer<br/>ffmpeg · ducking · loop/trim · EDL cuts]
  hub --> index[Track index<br/>tags + license + embeddings · SQLite · optional LanceDB]

厳守事項：数 MB に及ぶ動画の生データを MCP ペイロード経由で送信しないでください。 ローカルに保存し、asset_id を渡します。ループバック、file://、プライベート IP は拒否されます（SSRF）。

VideoSonic のプロファイル

分析結果は段落ではなく、構造化された JSON で返されます。

{
  "duration_sec": 18.4,
  "aspect": "9:16",
  "content_type": "lifestyle",
  "has_speech": true,
  "speech_coverage": 0.62,
  "existing_music": false,
  "overall_mood": ["warm", "playful"],
  "energy_mean": 0.62,
  "energy_curve": [{"t": 0, "energy": 0.3}, {"t": 4, "energy": 0.8}],
  "pacing": "fast-cut",
  "scenes": [{"start": 0, "end": 3.2, "description": "cafe exterior", "energy": 0.4}],
  "hook_window": [9.0, 15.0],
  "suggested_bpm": [95, 118],
  "avoid": ["dark cinematic drone", "aggressive trap", "lyrics-dense"],
  "search_queries": ["warm acoustic pop instrumental cafe"],
  "platform_hint": "instagram_reel",
  "analyzer": "local"
}

• 主な方式： GEMINI_API_KEY が設定されている場合は、Gemini の動画理解を使用します。
• フォールバック： ffmpeg のシーン切り替えと、WAV のエネルギー／無音／ZCR ヒューリスティックを使用します。インストールされている場合は、faster-whisper、scenedetect、librosa も任意で使用できます（pip install 'sonicmatch-mcp[local-vl]'）。

音楽ハブ

ライセンスを最優先にした、プラグイン式です。v0 に同梱されるものは次のとおりです。

アダプター	使用条件	ライセンスの実情
Seed catalog (data/seed_tracks.json)	常時	CC0／CC-BY の Reel 用音源20曲＋ボーカル音源のテスト用データ1件＋CC-BY-NC のテスト用データ1件（NC は自動で推奨されません）
Jamendo	JAMENDO_CLIENT_ID	CC。商用利用の可否を確認してください
Freesound	FREESOUND_API_KEY	CC。楽曲よりも音源やループに適しています
User library JSON	SONICMATCH_LIBRARY_PATH / EPIDEMIC_LIBRARY_PATH / ARTLIST_LIBRARY_PATH	すでにご自身でライセンスを取得済みです。有料サイトをスクレイピングすることはありません
Generate	generate_bed	常に source=generated。実際のモデルに差し替えない限り、ローカルのサイン波デモを使用します

ランキングの重み付け：ムード／エネルギー → 話し声がある場合はインストゥルメンタル → 長さ／ループ → BPM とカット率の比較 → ライセンスの適合性 → タグ埋め込みのコサイン類似度 → ユーザーの制約。recommend_bgm は、商用利用不可のトラックと生成トラックを順位を下げるのではなく、候補から除外します。

トラックは SQLite（~/.cache/sonicmatch-mcp/db/tracks.sqlite）に、24次元のタグ埋め込みとともにインデックス化されます。lancedb がインストールされている場合は（pip install 'sonicmatch-mcp[embeddings]'）、ベクトルもそこにアップサートされます。

意図的に、シードトラックにリモートの音声ファイルは含めていません（実際に権利を保有するファイルをホストしてください）。preview_mix は CC0 のデモ用音源を合成するため、ミキサーはオフラインでも動作します。generate_bed はカタログに該当するものがない場合のフォールバックであり、広告への使用許可は得ていません。

Docker

docker build -t sonicmatch-mcp .
# Loopback-only publish. The process inside the container has no HTTP auth.
docker run --rm -p 127.0.0.1:8765:8765 -v sonic-cache:/data/cache sonicmatch-mcp

ロードマップ

新しいツールよりカタログを優先します。

• Freesound アダプター（ループ／音源）
• SQLite のタグ埋め込み（＋任意の LanceDB エクストラ）
• ユーザー所有の JSON プラグインとしての Epidemic Sound／Artlist（スクレイピングなし）
• ビートグリッドとシーン切り替えに基づく提案（EDL 風の suggest_cuts）
• MCP レジストリへの登録（server.json）
• source=generated としてマークされた生成ツール（ローカルデモ。実際のモデルへの差し替えはご自身の法的責任で行ってください）
• GitHub Release MCPB による公式 MCP レジストリへの登録（PUBLISH.md を参照）
• 非商用ライセンスを recommend_bgm の自動候補から除外
• Reel の編集者が実際に採用する、ホスト可能な音源付きのシード音源20曲
• 広告向けのデフォルトパスとして、ユーザー所有の Artlist／Epidemic JSON を使用
• 実際の CLAP 音声埋め込み
• PyPI プロジェクトのメタデータ、コンソールスクリプト、タグトリガー式の Trusted Publishing（.github/workflows/release.yml）
• PyPI への初回アップロード（uvx sonicmatch-mcp）。メンテナー向けの手順は PUBLISH.md にあります。2026-10-21 時点で、この名前は未登録でした。

これが優れたオープンソースプロジェクトになり得る理由

次の点を実現できれば、可能性があります。：（1）動画に特化した分析、（2）すべての行でライセンスを誠実に表示すること、（3）エディター向けの出力（フックイン／フックアウト、ダッキング、ミックス仕様）、（4）利用者が手元に残しておきたくなるカタログ。

YouTube Music の検索をラップするだけなら、可能性はありません。 また、最初の5件のおすすめが、使い古されたストック音源のように聞こえる場合も同様です。

初日から適用するリスク対策（スローガンではなく、コードで強制します）：

リスク	対策
Content ID	すべての rec/search/get_track に content_id_warning を含めます。CC/RF が「Content-ID 対応済み」とされることはありません。content_id_risk は unknown または likely であり、cleared にはなりません。
yt-dlp の利用規約／抽出器の不具合	SONICMATCH_ALLOW_YTDLP=1 が設定されていない限り、プラットフォーム URL の取り込みは無効です。失敗時は YTDLP_EXTRACTOR に分類し、ローカルファイルを渡すよう案内します。
アップロードサイズ／SSRF	リモートからの取り込みは HTTPS のみに限定し、file://、ループバック、プライベート IP を禁止します。ファイル、HTTP、yt-dlp の --max-filesize に SONICMATCH_MAX_DOWNLOAD_MB（デフォルトは 200）を適用します。
「トレンド」は閉じた Meta グラフ	トレンド／バイラル／IG オーディオ／TikTok サウンドのクエリには、空の結果と TRENDING_UNAVAILABLE を返します。recommend_bgm は常に trending_available=false を設定します。
生成モデルの商用利用条件	i_understand_not_commercially_cleared=true が設定されていない場合、generate_bed は処理を拒否します。生成したトラックは、自動の recommend_bgm の対象外です。

ユースケース

IG リール／ストーリー · Shopee の商品クリップ · YouTube Shorts エージェント · CapCut／Premiere コンパニオン · キャンパスの振り返り動画 · ポッドキャストクリッパー · 旅行 Vlog の一括処理 · ブランドキットの固定（BPM＋ボーカルなし） · サイレント映画／アクセシビリティ · マルチエージェントスタジオ。

コントリビューション

CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · CHANGELOG.md · 初めての方におすすめの Issue

ライセンス

MIT。トラックのライセンスは、リポジトリのライセンスとは独立しています。

CodeCrafter より。