Audio MCP

audio-mcp

**为 AI Agent 提供音频感知能力。**大模型听不见声音。这个 MCP 服务 会将声音转换成它们能够推理的内容：测量结果、通俗易懂的问题报告、频谱图、音符列表、事件时间线、转录文本和前后对比。它还可以编辑和合成音频，让 Agent 能够循环处理：制作或修复声音 → 测量 → 查看 → 验证更改。

所有操作都在本地运行。无需 GPU，也无需 API 密钥。核心依赖：numpy、scipy、soundfile、matplotlib。

以下是随附演示 scripts/demo.py 的真实输出（JSON 已简化）：

> audio_analyze voice_raw.wav          # speech recorded with mains hum and hiss
  levels: lufs_integrated -32.16, true_peak_dbtp -11.76, clipped_samples 0
  issues: [warning] Mains hum at 60 Hz (peaks at 60, 180 Hz). Fix: notch each with
                    {"op":"eq","hz":60,"db":-30,"q":30}, {"op":"eq","hz":180,"db":-30,"q":30};
                    for voice, highpass at ~80-100 Hz also removes the fundamental.
          [info]    Noise floor around -33.4 dBFS in the quietest parts; hiss or background noise may be audible.

> audio_events sfx.wav                 # a zap, a noise hit, another hit, a rising chirp
  0.09-0.36s | -4dB  | tonal | balanced          | glide G#6->B3 (-33st) | sharp attack
  0.59-0.69s | -16dB | noisy | very bright/harsh | sharp attack
  ...

> audio_melody melody.wav              # "Mary Had a Little Lamb", transcribed blind
  E4(0.23) D4(0.24) C4(0.23) D4(0.24) E4(0.25) E4(0.25) E4(0.5) D4(0.24) D4(0.26) D4(0.49) E4(0.25) G4(0.26) G4(0.47)

工具

工具	为 Agent 提供的内容
audio_analyze	峰值、真峰值、RMS、LUFS 响度、削波、直流偏移、响度迷你图、静音和噪声底、立体声相关性／宽度／平衡、频段能量、明亮度、音调／噪声特征、最强频率对应的音符名称、音高、起音、节奏、边缘咔嗒声、循环接缝质量，以及一份用通俗语言描述问题并提供建议修复方案的 issues 列表
audio_events	将音频拆分成不同声音，并逐个描述：时间、音量、起音、音调／噪声特征、明亮度、音高或滑音
audio_view	波形和／或频谱图 PNG，可选叠加音高。每一列都覆盖完整时间范围，因此长文件中的短促咔嗒声也不会被跳过
audio_timeline	随时间变化的音量和明亮度。以流式方式读取文件，因此适用于任意时长的录音
audio_melody	单行转录：音符、时间、音分、简洁文本
audio_transcribe	使用本地 Whisper 将语音转成文本：带时间戳的词语、语言、语速、长停顿和不确定的词语 (可选附加功能)
audio_compare	A/B 摘要、指标差异、各频段的 dB 变化、已修复或新出现的问题，以及空值测试（是否完全相同？是否仅增益变化？是否有轻微变化？）
audio_process	按顺序执行编辑操作链，并写入一个新文件：增益、峰值／LUFS 标准化、真峰值限制器、压缩器、降噪、RMS 标准化、裁剪、淡入淡出、截取、补齐、高通／低通、峰值 EQ、搁架滤波、移除直流偏移、极性、单声道／立体声、重采样、反转、无缝循环交叉淡化、混音、追加
audio_batch_survey	检查文件夹的一致性（响度异常值、采样率／声道／格式混杂、开头静音时长不一致），并返回可直接运行的修复操作
audio_batch_process	对多个文件应用同一编辑操作链，并将文件写入输出文件夹
audio_synthesize	声明式合成器：带限振荡器（可控制相位）、不同颜色的噪声（粉红噪声／棕色噪声可无缝循环）、扫频、ADSR、颤音、震音、滤波器、声像、音符序列，以及精确测试信号（脉冲、直流、静音）
audio_info	文件的元数据，或文件夹中的音频文件列表
audio_check_delivery	根据交付规范（Apple Podcasts、Spotify、YouTube、EBU R 128、ATSC A/85、ACX 有声书、游戏音效）进行通过／不通过检查，提供引用来源，并给出已在你的文件上尝试过的修复方案
audio_check_game_project	检查 Godot 4 项目的音频：各类别的响度一致性、循环设置和咔嗒声接缝、缺陷，以及损坏或未使用的 res:// 引用

原生读取 WAV、FLAC、OGG/Vorbis、Opus、MP3、AIFF 和 CAF（通过 libsndfile）。安装 FFmpeg 后，还可读取 M4A/AAC（手机、Zoom、语音备忘录）、WMA 和视频文件中的音频（MP4、MOV、WebM、MKV）： Windows 上运行 winget install Gyan.FFmpeg，macOS 上运行 brew install ffmpeg，Debian/Ubuntu 上运行 sudo apt install ffmpeg， 或将 AUDIO_MCP_FFMPEG 设为二进制文件路径。每个文件在每个会话中只解码一次。编辑后的文件将以 WAV/FLAC/OGG/AIFF/MP3 格式写入。

交付检查

audio_check_delivery 会告知你文件是否符合平台规格；如果不符合，还会说明如何修复。每项标准都会显示要求、测量结果以及是否通过。建议的修复方案是一组按顺序执行的 audio_process 操作（先处理噪声，再调整增益，最后进行真峰值限制），工具已在你的文件上模拟了这组操作；工具还会明确指出哪些问题无法自动修复，或何时需要由人工判断严重的背景噪声。规格数值会注明官方来源和核查日期。

游戏项目（Godot 4）

audio_check_game_project(project_dir) 会审查 Godot 4 项目中的所有 .wav/.ogg/.mp3 文件。它会根据文件夹和文件名推断类别（UI、音效、语音、音乐、环境音），也可以使用你自己的映射。它会读取 .import 设置，找出不会循环播放的音乐、无限循环的音效，以及会产生咔嗒声的循环接缝。它会比较各类别内的响度（短音效按最响时刻计算，音乐按积分 LUFS 计算），并报告异常值及可直接运行的修复方案。它还会扫描场景和脚本，查找损坏、大小写错误或未使用的 res:// 音频引用。它绝不会修改项目。

安装

pip install audio-mcp              # or: uv tool install audio-mcp
pip install "audio-mcp[speech]"    # adds audio_transcribe (faster-whisper; downloads a ~145 MB model on first use)

将其连接到 MCP 客户端

Claude Code

claude mcp add audio -- uvx audio-mcp
# or, if installed with pip:
claude mcp add audio -- audio-mcp

Claude Desktop、Cursor 和其他客户端（JSON 配置）：

{
  "mcpServers": {
    "audio": { "command": "uvx", "args": ["audio-mcp"] }
  }
}

然后可以提出诸如 “检查 ./sfx 中的音效是否有问题”、“为播客清理 interview.wav” 或 “设计一个简短的 UI 确认音效，并检查它是否刺耳” 之类的请求。

限制文件访问

默认情况下，该服务可以读取和写入你的用户帐户有权访问的任何文件。若要限制访问范围，请将 AUDIO_MCP_ALLOWED_DIRS 设置为目录列表（Windows 上以 ; 分隔，其他系统上以 : 分隔）：

{ "command": "uvx", "args": ["audio-mcp"], "env": { "AUDIO_MCP_ALLOWED_DIRS": "/home/me/audio" } }

路径会在解析 .. 和符号链接后进行检查。其他设置：AUDIO_MCP_MAX_SECONDS（每次调用载入内存的最大片段长度，默认值为 1800）、AUDIO_MCP_WHISPER_MODEL（默认值为 base）、AUDIO_MCP_ROOT（相对路径的基目录）。

如何检查准确性

测试主要使用通过构造已知正确答案的合成信号，因此检查的是正确性，而不只是“不会崩溃”：

• **响度：**我们的流式 BS.1770 测量器在 8 至 96 kHz 范围内与 pyloudnorm 的精确滤波模式结果相差不超过 0.01 LU；对 EBU 参考音（997 Hz，0 dBFS）的测量结果为 −3.01 LUFS。
• 限制器：+15 dBTP 输入信号的输出恰好为 −1.0 dBTP，且安全削波没有影响任何采样点。
• **音高和旋律：**可以逐音符还原正弦波、啁啾声和合成旋律，包括重复音符；从 82 Hz 到 1760 Hz 的音高误差不超过 1 音分。
• **速度、起音、事件、静音、立体声相位、嗡声、削波、对齐偏移：**每项都通过与构造信号进行比对来检查。
• 契约测试会针对每种内容类型（静音、直流、噪声、满幅方波）、长度（1 个采样点至 3 秒）、格式（16 位/24 位/浮点 WAV、FLAC、Vorbis）、声道数（1、2、6）和采样率（8–96 kHz）运行每种工具。每次调用都必须成功，或抛出能说明原因的 AudioError。
• **内存：**分析采用分块处理。分析一个 20 分钟、48 kHz 的立体声文件约需 19 秒，峰值内存约为 1.2 GB，其中 0.7 GB 用于音频本身。

设计原则

• 默认绝不执行破坏性操作。 编辑后会写入 <name>_processed.wav；只有设置 overwrite=true 才会覆盖，并且批量输出不能指向输入文件夹。
• 错误信息会说明下一步该怎么做。 遇到未知操作时，会列出所有操作及其参数；遇到无法解码的文件时，会列出支持的格式，并说明如何为其他格式安装 FFmpeg。意外错误会作为 bug 报告，而不是被隐藏。
• 如实说明不确定性。 检测到和弦时会设置 polyphony_likely，而不会给出自信却错误的音高；置信度较低的节奏会附带低置信度说明；会列出 Whisper 无法确定的词语；对于时长不足 0.4 秒的片段，LUFS 为 null。
• 输出简洁。 四舍五入的数字、迷你图和单行事件摘要能让响应足够精简，适合放入 Agent 的上下文。

限制

• 音高、旋律和逐事件音高分析都假设一次只有一个音符。和弦和完整混音会被标记，但不会被转录。
• 降噪使用频谱门限处理稳定噪声（嘶嘶声、嗡嗡声、风扇声、房间底噪）。它无法去除咔嗒声、音乐或其他人声。sensitivity 过高会使轻柔的辅音变得含糊，因此请使用 audio_transcribe 检查语音编辑效果。
• 节奏使用经典的自相关方法估算；对于复杂音乐，可能会出现半拍或双倍节奏的错误。
• 这些工具会描述声音，但不会评判审美（“听起来是否令人满意？”）。

参考信号

audio-mcp-assets 是一个公有领域测试和校准音频包，包含音调、扫频、校准噪声、响度、立体声和相位测试、脉冲及问题文件。一个 AI Agent 仅使用这些工具构建了该资源包。每个文件都经过两次验证，并与已知真值进行比对，其中一次验证独立于本项目进行。

贡献

欢迎个人和 AI Agent 提交改进。请参阅 CONTRIBUTING.md；AI 编码 Agent 还应阅读 AGENTS.md。功能的标准是专注做好一件事，并提供针对已知真值的测试。

许可证

MIT