Audio Sonic MCP

🎵 Audio Sonic MCP

只需在本地调用一次，即可将任意歌曲转化为结构化的“声音特征”——提取节奏、调性、512 维 CLAP 氛围嵌入、人类可读的氛围标签和制作档案。

Audio Sonic MCP 完全在本地计算机上运行（无需 API 密钥、外部服务或云依赖），并提供两个高品质入口，共用同一套高保真音频分析引擎：

	适用对象	核心接口与机制
🤖 MCP 服务	大模型、AI Agent 和 IDE（Claude、Cursor、Windsurf、Cline）	对 YouTube URL 进行异步、发起后即返回的分析，避免音频处理耗时过长而阻塞客户端大模型。
🎚️ 本地 CLI	音乐人、声音制作人和音频工程师	深度命令行工具，针对本地文件进行整首歌曲的多窗口分析并生成高保真输出。

---

🎹 快速预览：你将获得什么

1. 适合音乐人的 CLI 摘要（--summary 模式）

🎵 SONIC SIGNATURE — my_demo.mp3  (3:24)

  TEMPO    153.8 BPM  (steady)
  KEY      G Major  ·  shifts to G Phrygian @0:30   (confidence 74%)
  VIBE     aggressive · dark · driving · hip-hop · gritty

  PRODUCTION
     Vocals     forward
     Punch      0.62  (moderate)
     Stereo     wide
     Low end    ~55 Hz dominant

  Overall confidence: 88%   ·   analyzed in 0:28 (GPU-accelerated)

2. 完整 JSON（MCP 默认返回，CLI 默认输出）

{
  "header": {
    "job_id": "sig_a3f9b2c1",
    "status": "success",
    "confidence_score": 0.88,
    "source_metadata": {
      "title": "Acoustic Vibe Demo",
      "duration_sec": 204,
      "source_type": "file"
    }
  },
  "sonic_signature": {
    "bpm": 153.8,
    "bpm_engine": "madmom",
    "bpm_variable": false,
    "key": "G Major",
    "key_variable": true,
    "key_map": [
      { "start_sec": 0.0,  "end_sec": 30.0, "key": "G Major" },
      { "start_sec": 30.0, "end_sec": 90.0, "key": "G Phrygian" }
    ],
    "mode_confidence": 0.74,
    "vibe_vector": [0.012, -0.034, "... 512 float dimensions ..."],
    "vibe_tags": ["aggressive", "dark", "driving", "hip-hop", "gritty"],
    "production_profile": {
      "vocal_presence": "forward",
      "transient_punch": 0.62,
      "stereo_width": "wide",
      "dominant_freq_peaks_hz": {
        "harmonic": [55.0, 110.2],
        "percussive": [125.0, 250.1]
      }
    }
  },
  "telemetry": {
    "inference_time_sec": 28.0
  }
}

---

⚡ 主要功能

• 🥁 节奏与节拍跟踪 — 完整计算 BPM，检测速度变化漂移并进行瞬态窗口分析。
• 🎹 调性与和声映射 — 计算音乐的结构性调性和调式，并生成详细的 key_map，跟踪各乐段之间的转调。
• 🌈 氛围与风格嵌入 — 使用零样本音乐词汇分类，生成 512 维 CLAP 嵌入和人类可读的风格标签（涵盖能量、质感、情绪和流派）。
• 🎚️ 制作分析 — 测量人声空间感、瞬态冲击系数、立体声宽度和主要频率峰值。
• 🤖 MCP 原生系统 — 完整提供 4 个标准化的 Model Context Protocol 工具，可即时集成到 AI 工具中。
• 🪶 稳健的优雅降级 — 存在 CUDA GPU 时自动使用，否则回退到 CPU；未安装重量级深度学习包（[clap]）时，则优雅降级为 HPSS 和标准 librosa 特征数组。
• 🔒 100% 离线且私密 — 所有转换、分离和推理均在本地完成。

---

📦 安装与设置

系统前置要求

确保已安装 Python 3.10+ 和 FFmpeg，并且可通过系统 PATH 访问。

安装 FFmpeg：

• macOS：brew install ffmpeg
• Linux（Debian/Ubuntu）：sudo apt update && sudo apt install -y ffmpeg
• Windows：通过 PowerShell（管理员）运行 winget install Gyan.FFmpeg，或从 ffmpeg.org 手动下载，并将 bin 目录添加到系统环境变量中。

---

分步安装

1. 克隆代码库

   git clone https://github.com/ripunjay-kashyap/audio-sonic-mcp.git
   cd audio-sonic-mcp
   

2. 初始化虚拟环境

   python -m venv .venv
   # Activate on macOS/Linux:
   source .venv/bin/activate
   # Activate on Windows (PowerShell):
   .venv\Scripts\activate
   

3. 安装依赖项 在轻量级核心引擎和完整的高保真 ML 套件之间进行选择：

   • 选项 A：完整的高保真 ML 套件（推荐） 包含分离音轨（Demucs）和零样本氛围向量（CLAP）。需要约 4 GB 磁盘空间。

     pip install -e ".[clap]"
     

   • 选项 B：轻量级核心处理管线 使用标准数字信号处理（HPSS/librosa）。安装快速，占用空间小。

     pip install -e .
     

说明

可选的 [clap] 组件会安装 torch、torchaudio、transformers 和 demucs。如果未安装这些依赖项，服务会自动切换到轻量级替代方案（使用 HPSS 而非 Demucs、使用标准特征矩阵而非 CLAP 向量，并省略 vibe_tags）。

---

🤖 MCP 客户端配置指南

Audio Sonic MCP 会注册为标准包脚本。这样，你可以直接从虚拟环境的 bin 文件夹使用全局可执行文件名（audio-sonic-mcp）运行它，也可以手动运行脚本文件。

1. Claude Desktop 设置

打开 Claude 配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

将服务添加到 mcpServers 对象中：

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "C:\\path\\to\\audio-sonic-mcp\\.venv\\Scripts\\audio-sonic-mcp.exe",
      "args": [],
      "env": {
        "JOBS_ROOT": "C:\\path\\to\\audio-sonic-mcp\\jobs"
      }
    }
  }
}

重要

Windows 用户：JSON 配置路径中始终使用双反斜杠（\\）。将可执行文件路径直接指向 .venv\Scripts\ 目录中的 .exe 文件。

---

2. Cursor IDE 集成

若要将 Audio Sonic MCP 集成到 Cursor 的 AI 面板中：

1. 前往 Settings ➔ Features ➔ MCP。
2. 点击 + Add New MCP Server。
3. 填写参数：
   • Name：audio-sonic-mcp
   • Type：command
   • Command：/path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp（Windows 上使用 .exe 扩展名）

---

3. Windsurf 集成

打开 Windsurf MCP 配置文件（通常位于 ~/.codeium/windsurf/mcp_config.json），并追加以下配置：

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "/path/to/audio-sonic-mcp/.venv/bin/python",
      "args": ["/path/to/audio-sonic-mcp/server.py"],
      "env": {
        "JOBS_ROOT": "/path/to/audio-sonic-mcp/jobs"
      }
    }
  }
}

---

4. Cline（VS Code 扩展）设置

打开 Cline 的 MCP 设置文件（通常位于 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 或相应平台的存储位置），并添加：

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "/path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp",
      "args": [],
      "env": {
        "JOBS_ROOT": "/path/to/audio-sonic-mcp/jobs"
      }
    }
  }
}

---

🤖 AI Agent 和大模型的交互流程

大模型会通过读取服务公开的工具定义，自动了解如何使用此服务。由于音轨分离和 CLAP 嵌入的计算开销较大，Audio Sonic MCP 使用异步即发即弃任务模式。

大模型自动化工作流

  [User Prompts LLM]
          │
          ▼
1. Submit URL ──────────────► [Tool: get_sonic_signature]
                                      │ (Returns Job ID instantly)
                                      ▼
2. Notify User ◄───────────── [LLM acknowledges job is queued]
          │
          ├───► 3. Wait 10-15s (Or proceed with other tasks)
          │
          ▼
4. Check Progress ──────────► [Tool: get_job_status]
                                      │ (Checks status: running/success/error)
                                      ▼
5. Present Signature ◄─────── [LLM formats rich output for user]

可尝试的自然语言提示词

• “检查我的 audio-sonic-mcp 服务的运行状况，确认所有 ML 组件都已就绪。”
• “提交这首 YouTube 曲目进行声音分析：https://www.youtube.com/watch?v=XXXXXX。”
• “检查我的声音特征任务 sig_a1b2c3d4 的进度，完成后总结 BPM、制作宽度和氛围。”

---

🎚️ CLI 用法（本地文件）

对于直接在终端中工作的音乐人、工程师和制作人，你无需运行任何后台服务，即可直接分析完整的本地文件：

# Get a visual, musician-friendly sonic signature digest (recommended)
python analyze_file.py "my_demo.wav" --summary

# Print full raw JSON directly to the stdout stream
python analyze_file.py "my_demo.wav"

# Dump JSON payload to a file while keeping the stdout clean
python analyze_file.py "my_demo.wav" > signature.json

CLI 命令选项参考

选项	简写	描述
path	无	本地音频文件的绝对或相对路径（必填）。
--summary	-s	打印格式清晰的终端摘要，而非标准 JSON。
--no-vector	无	生成 JSON 特征签名，但省略占用空间较大的 512 维 vibe 浮点数组。
--out FILE	-o	将最终 JSON 特征签名直接输出到指定文件。
--keep	-k	不删除 jobs/ 中的中间 WAV 文件或分离出的音轨文件。
--job-id ID	-j	显式定义内部标识符（适用于批处理脚本）。

支持的文件格式：wav、mp3、flac、ogg、m4a、aac。

---

🔧 环境变量参考

在当前终端会话、容器环境或 MCP 配置文件的 env 块中声明以下变量，以配置环境选项：

变量	默认值	描述 / 实际用途
JOBS_ROOT	./jobs	工作区目录，用于处理音频文件、临时转换的 WAV 文件和分离出的音轨文件。
KEEP_JOB_FILES	未设置	设置为 1 或 true，可将分离出的音轨 WAV 文件保留在磁盘上（每个任务会额外占用约 75 MB，便于排查问题）。
FILE_MAX_DURATION_SEC	600	本地文件处理时长的安全上限（YouTube 下载时长上限为 60 分钟）。
FFMPEG_BIN	未设置	如果系统 PATH 中没有 ffmpeg，则指定包含 ffmpeg 二进制文件的文件夹路径。
YTDLP_PROXY	未设置	直接传递给 yt-dlp 的 HTTP/SOCKS 代理字符串，用于绕过速率限制或网络封锁。
TRANSPORT_MODE	stdio	服务监听的传输方式：stdio（默认，适用于本地 MCP 客户端）、sse（通过 HTTP 提供远程 MCP）或 hybrid（MCP SSE 和来自 app_cloud.py 的 REST API）。sse/hybrid 需要 pip install ".[cloud]"。
PORT	8000	当 TRANSPORT_MODE 为 sse 或 hybrid 时使用的监听端口。stdio 模式下会忽略此项。

---

🐳 Docker / Podman 执行

如果不想设置本地 Python 库，可通过容器运行，将 FFmpeg、yt-dlp 和核心 Python 依赖项（基于 CPU 的处理流水线）封装在一起：

# Build the container image
docker build -t audio-sonic-mcp .

# Run the MCP server over stdio, mounting local folders for job persistence
docker run -i --rm \
  -v "$(pwd)/jobs:/app/jobs" \
  -v "$(pwd)/models:/app/models" \
  audio-sonic-mcp

若要将 Claude Desktop 连接到 Docker 容器，请配置 claude_desktop_config.json：

{
  "mcpServers": {
    "audio-sonic-mcp-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/absolute/path/to/jobs:/app/jobs",
        "-v", "/absolute/path/to/models:/app/models",
        "audio-sonic-mcp"
      ]
    }
  }
}

---

⚙️ 底层工作原理

Audio Sonic MCP 流水线采用模块化构建，并使用事务检查点确保可靠性。

  LLM Agent / Claude Desktop                 Musician (Terminal)
            │                                          │
            │  MCP (stdio JSON-RPC)                    │  analyze_file.py
            ▼                                          ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  Modular 6-Stage Analysis Pipeline                                       │
│                                                                          │
│  Stage 1: Ingestion   │ Pre-checks format, scans duration metadata       │
│  Stage 2: Download    │ Fetches audio tracks via yt-dlp (URLs only)      │
│  Stage 3: Conversion  │ normalizes sample formats to 44.1kHz WAV (FFmpeg)│
│  Stage 4: Separation  │ Splits stems: Vocals, Drums, Bass, Other (Demucs)│
│  Stage 5: Analysis    │ Computes BPM, modulations, key, punch (librosa)  │
│  Stage 6: Embeddings  │ Generates 512-dim zero-shot music vibe tags (CLAP)│
└─────────────────────────────────────┬────────────────────────────────────┘
                                      ▼
             Result Payload: (header · sonic_signature · telemetry)

1. 音轨分离：Meta AI 的 Demucs (mdx_extra) 会将曲目分离为独立音轨（vocals、drums、bass、other）。如果缺少该组件，则会平稳回退到谐波-打击乐源分离（HPSS）。
2. 分析引擎：librosa 提取节奏和调性结构，并将和弦模式和次低音变化与 Krumhansl-Schmuckler 和 Phrygian 模板引擎进行匹配。
3. 语义氛围标签：LAION CLAP（laion/larger_clap_music_and_speech）会针对覆盖范围广泛的审美描述词（情绪、质感、流派）进行零样本推理，并从不同风格类别中选出排名靠前的候选项。

---

🩺 弹性与故障排查

1. 首次设置时下载延迟

在首次使用完整 ML 流水线进行分析任务时，demucs 和 transformers 会下载预训练模型权重（Demucs 约 400 MB，CLAP 约 200 MB）。

• 服务会将下载进度指示信息重定向到 stderr，以确保不会破坏 JSON-RPC 标准流。
• 下载期间，get_job_status 会一直显示 running。请根据网络速度等待 1–3 分钟。之后启动耗时不到 10 秒。

2. FastMCP 并发控制

多阶段架构上的模型推理会大量占用 CPU/VRAM。为防止消费级硬件和虚拟环境崩溃（出现 OutOfMemory 异常），Audio Sonic MCP 会强制使用严格的全局串行锁（CONCURRENCY_LOCK）。

• 如果同时提交多个 URL，它们将按顺序处理。
• 在后续任务等待管线队列时，轮询 get_job_status 会显示 queued 或 running。

3. Windows Librosa 死锁修复

Windows 上 FastMCP 的线程分发可能导致后台工作线程中的 Numba 编译死锁。为避免这种情况，Audio Sonic MCP 会在启动时执行预热例程（_prewarm_librosa() 和 _prewarm_demucs()）。它会在启动 RPC 监听器之前，强制在主线程中对重采样、HPSS 和单声道混音函数进行 JIT 编译。

4. BPM 准确度和 bpm_engine 字段

节奏由 madmom 的 RNN 节拍跟踪器估算。madmom 是一个可选依赖：它已停止维护（最新版本为 0.16.1，分类器仅支持到 Python 3.7），且需要进行 Cython 构建，因此无法在所有环境中可靠安装，也不包含在默认安装中。

如果 madmom 不可用，管线会回退到 librosa。对于稳定的四拍节奏素材，这种回退效果不错，但可能会锁定到真实节奏的2:3 倍或八度倍数——在我们的一个回归测试样例中，真实值为 148 BPM，而它报告为 99.4 BPM。

因此，报告节奏时始终会注明依据。每个负载都包含一个 bpm_engine 字段，用于标明实际生成该数值的引擎：

bpm_engine	含义
madmom	RNN 节拍跟踪器 — 精度完整。
librosa-fallback	madmom 不可用；BPM 仅供参考，偶尔可能出现八度或三连音误差。

check_health 会明确报告 madmom 的状态。要启用准确模式：

pip install ".[beats]"

如果在较新的 Python 版本上构建失败，请在分析环境中使用 3.10 — madmom 没有适用于更新版本解释器的 wheel。

5. 使用 check_health 进行诊断

如果服务报告状态为 degraded，或缺少工具，请调用 check_health 工具或查看 CLI 警告。它会检查：

• 执行路径上是否有 ffmpeg。
• Python 包（librosa、soundfile、mcp 等）的安装状态。
• 可选的 madmom 节拍跟踪器是否存在，以及因此将使用哪个 bpm_engine。
• 对 JOBS_ROOT 目录的访问权限。

---

🛠️ 开发与测试

在虚拟环境中运行单元测试，使用合成音频波形验证数学管线：

# Install development test framework
pip install -e ".[dev]"

# Execute full suite (requires no network or model downloads)
pytest

# Test specifically CLI execution code paths
pytest tests/test_cli.py

---

📄 许可证

根据 MIT License 发布。详情请参阅 LICENSE。

© 2026 Ripunjay Kashyap。保留所有权利。