Sonicmatch

Sonicmatch

面向视频、可安全授权使用背景音乐的 MCP 服务。 它分析的是视频素材，而不是脚本，并返回候选曲目清单、一个 12–20s 的钩子片段，以及 ffmpeg 侧链压低音量规格。

软件包 / 命令行工具：sonicmatch-mcp。这是一个 Model Context Protocol 服务，可供 Claude Desktop、Cursor、Codex 及其他 MCP 客户端使用。拖入 Instagram Reel、YouTube Short 或 TikTok 风格的短片，即可获得免版税 / Creative Commons 曲目匹配结果，每一行都会标明许可。

视频匹配背景音乐早已存在。我们的切入点不是“我也能匹配音乐”：

• 它分析视频素材，而不是脚本
• 它会返回一个钩子片段窗口和 ffmpeg 侧链压低音量规格
• 它是原生面向 Agent 的
• 它会标明许可，而不是作虚假保证

目录质量决定成败。增加更多工具无济于事。

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 / IG 官方曲库
排名曲目、预览 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，并推荐 5 首器乐背景音乐。然后使用侧链压低音量混合最合适的曲目，并给我 ffmpeg 命令。

这个提示词就是产品。按照下文安装、配置 Claude Desktop、Cursor 或 Codex，然后粘贴这段提示词即可。

快速开始

需要 Python 3.10+，并且 ffmpeg / ffprobe 已加入 PATH。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

种子目录包含约 20 条 Reel 编辑场景的曲目记录（咖啡馆、产品、出镜讲话、旅行、美食、时尚、活动），另有一段人声素材和一段 CC-BY-NC 素材。无需 API 密钥即可运行。Gemini、Jamendo 和 Freesound 都是可选项；不可用时会在工具响应中附带说明。种子记录有意不提供托管音频——preview_mix 会合成演示背景音乐。对于真实广告，请将 SONICMATCH_LIBRARY_PATH / EPIDEMIC_LIBRARY_PATH / ARTLIST_LIBRARY_PATH 指向你已获授权的 JSON 文件。

变量	必需	用途
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–20s 的钩子片段起止点、语音闪避、ffmpeg 配方，以及适用于 CapCut / Premiere / DaVinci / 你的 Agent 的混音规格。
• 原生适配 Agent 的 MCP。 为 Claude Desktop 和 Cursor 提供 stdio；为 Web 编辑器提供流式 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	单首曲目的元数据、许可信息、署名信息、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	保存 BPM / 情绪 / 无人声设置，供 recommend_bgm(brand_kit=…) 使用
analyze_batch	最多分析 20 条片段 → 情绪聚类 + 共享迷你播放列表

还附带一个提示词模板：“像 IG 音乐贴纸那样为这段视频配乐。”

产品规则（类似 Instagram，而非 Instagram）

• 当 speech_coverage > 0.25 时，优先选择纯音乐
• 推荐一个钩子片段，而非整首歌
• 说明推荐理由（平均每 0.8s 切换一次，112 BPM，温暖的黄金时刻）
• 始终返回许可信息 + 署名文本
• 提供 3–7 首曲目，而非 40 首
• 用户可以覆盖情绪 / 流派 / 无歌词 / 平台 / 能量设置
• 除非确实如此，否则绝不声称“已获 Instagram 官方贴纸授权”

示例

提示词：

我放入了 ./clip.mp4。请为 Instagram Reel 分析它，并推荐 5 首纯音乐背景音乐。然后对首选曲目进行混音并应用闪避处理，再给我 ffmpeg 命令。

Agent 应按以下顺序调用：

1. 使用本地路径调用 ingest_video。结果是 asset_id，而不是视频字节。
2. 调用 analyze_video_music，并将 platform_hint 设为 instagram_reel。
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（通过 uvx，参数为 ["sonicmatch-mcp"]）。从克隆目录运行："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 = ""

也可以通过命令行配置：

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。点击页面上的 Use the sample clip，或下载 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]

硬性规则：**绝不通过 MCP 负载发送数 MB 的原始视频。**在本地存储，并传递 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 版本包含：

适配器	适用条件	许可证情况
种子目录（data/seed_tracks.json）	始终可用	20 首 CC0 / CC-BY Reel 配乐 + 一个带人声样例 + 一个 CC-BY-NC 样例（不会自动推荐 NC）
Jamendo	JAMENDO_CLIENT_ID	CC，需检查是否可用于商业用途
Freesound	FREESOUND_API_KEY	CC，适合配乐和循环音频，不适合歌曲
用户音乐库 JSON	SONICMATCH_LIBRARY_PATH / EPIDEMIC_LIBRARY_PATH / ARTLIST_LIBRARY_PATH	已获得你的授权；我们不会抓取付费网站
生成	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 扩展）
• Epidemic Sound / Artlist 作为用户自有 JSON插件（不抓取）
• 节拍网格与场景切换建议（类似 EDL 的 suggest_cuts）
• MCP 注册表条目（server.json）
• 生成工具，标记为 source=generated（本地演示；替换为真实模型的法律风险由你自行承担）
• 通过 GitHub Release MCPB 列入官方 MCP 注册表（参见 PUBLISH.md）
• 从自动 recommend_bgm 推荐中排除非商业用途许可证
• 提供 20 首 Reel 编辑人员会实际采用的配乐，并由你托管音频
• 将用户自有的 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 搜索，或者前五条推荐听起来像剩下的库存配乐。

首日风险关卡（通过代码强制执行，而非仅仅喊口号）：

风险	关卡
Content ID	每个推荐/搜索/获取曲目的结果都包含 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 Reel / Story · Shopee 产品短片 · YouTube Shorts Agent · CapCut/Premiere 助手 · 校园回顾 · 播客片段剪辑工具 · 旅行视频批量处理 · 品牌套件锁定（BPM + 无人声）· 无声电影 / 无障碍体验 · 多 Agent 工作室。

贡献

CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · CHANGELOG.md · 入门问题

许可证

MIT。曲目的许可证独立于代码仓库许可证。

来自 CodeCrafter。