Audacitymcp

AudacityMCP

通过 Model Context Protocol 在 Audacity 中进行 AI 驱动的音频编辑

快速入门 • 为什么选择 AudacityMCP？ • 管线 • 工具参考 • 故障排查

AudacityMCP 可将任何兼容 MCP 的 AI 助手连接到 Audacity，让它能够通过 144 种工具全面控制音频编辑，涵盖效果处理、清理、母带制作、转录等功能。与 AI 助手对话，它就会实时编辑你的音频。

无需云服务。音频处理无需 API 密钥。一切都通过 Audacity 的命名管道接口在本地运行。

如果这个项目对你有用，点个星标可以帮助更多人发现它——这就是本项目全部的推广预算。想帮忙维护项目？点击上方的 赞助徽章。

演示

兼容性： AudacityMCP 适用于 Audacity 3.x。Audacity 4 移除了 mod-script-pipe——本服务所驱动的脚本接口——且没有提供替代方案，因此 AudacityMCP 无法控制 Audacity 4。

正在运行 Audacity 4？ 这里有一个配套项目：Audacity4-MCP——通过 TCP JSON-RPC 桥接提供 159 种工具，涵盖编辑、选区、标签、破坏性和实时效果，以及 VST3 参数实时控制。

该项目目前仍处于早期 Alpha 阶段，且需要说明其配置要求：由于 Audacity 4 目前没有远程控制接口，因此需要使用从源代码构建的 Audacity 4 配套分支（Visual Studio、Qt 6.10、CMake、Ninja）。因此目前它更适合开发者，而非一般用户。Audacity 维护者已确认，内部迁移完成后将规划官方命令和 MCP 接口；届时应该不再需要该分支。

兼容产品

AudacityMCP 适用于任何支持 Model Context Protocol 的 AI 客户端：

• Claude Desktop — Anthropic 的桌面应用
• Claude Code — 命令行 Agent
• Cursor — 支持 MCP 的 AI 代码编辑器
• 其他任何兼容 MCP 的客户端

快速入门

1. 获取 AudacityMCP

选项 A： 点击上方绿色的 Code 按钮 → Download ZIP → 解压到一个文件夹

选项 B： 使用 git 克隆：

git clone https://github.com/xDarkzx/Audacity-MCP.git

2. 运行安装程序（自动完成其余所有设置）

Windows： 在文件资源管理器中双击 install.bat，或者——如果你已经在上面 git clone 步骤所用的终端中——直接在同一个 PowerShell/命令提示符窗口中继续：

cd Audacity-MCP
.\install.bat

macOS / Linux：

cd Audacity-MCP
bash install.sh

安装程序会完成 3 件事：从此本地文件夹（你刚刚下载/克隆的文件夹）安装 audacity-mcp（不会从 PyPI 或 GitHub 获取内容），在 Audacity 中启用 mod-script-pipe，并配置 Claude Desktop——无需手动编辑 JSON。安装程序会在修改任一配置文件前征求确认，事先准确说明将要执行的操作，并且在更改现有文件前始终先备份。想查看它会执行的所有操作，但不实际更改任何内容？添加 --dry-run：.\install.bat --dry-run / bash install.sh --dry-run。

注意：必须在此文件夹中运行 install.bat/install.sh——它们只会安装所在文件夹中的代码，不会自行下载任何内容。

{
  "mcpServers": {
    "audacity": {
      "command": "audacity-mcp"
    }
  }
}

3. 开始编辑

打开 Audacity，加载一些音频，然后与你的 AI 对话：

"Clean up this podcast recording"
"Master this track for Spotify, it's EDM"
"Transcribe this and add labels at each sentence"
"Add reverb with a large room, then export as FLAC"

必须先打开 Audacity。 AudacityMCP 通过 Audacity 的命名管道进行通信——它无法替你启动 Audacity。

请参阅完整的安装指南，了解所有平台和 MCP 客户端的详细设置说明。

为什么选择 AudacityMCP？

不使用 AudacityMCP： 你需要手动浏览菜单、凭耳朵调整效果参数、一次应用一个效果、查找 ACX 规格，并反复尝试，直到效果满意。

使用 AudacityMCP： 你只需用简单的英语描述需求，AI 就会处理其余事项——选择合适的效果、设置行业标准参数，并串联各项操作。

AudacityMCP 尤其适合：

• 播客创作者：无需音频工程知识，也能获得稳定、专业的音质
• 音乐人：需要使用适合曲风的设置快速制作母带
• 内容创作者：处理访谈、配音或现场录音
• 任何人：更愿意描述需求，而不是逐个点击菜单

它能做什么？

You:  "Clean up this podcast recording"
AI:   Runs auto_cleanup_podcast → HPF 80Hz → noise reduction → compression → safe loudness check

You:  "Master this track for Spotify, it's EDM"
AI:   Runs auto_master_music style=edm → HPF 30Hz → click removal → compression 2.5:1 → bass +2dB → loudness check

You:  "This is a noisy live recording, fix it up"
AI:   Runs auto_cleanup_live → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1

You:  "Transcribe this interview and add labels"
AI:   Runs transcribe_to_labels → faster-whisper transcription → Audacity labels at each timestamp

You:  "Add reverb to the vocals, then export as FLAC"
AI:   select region → reverb effect → export to FLAC

功能

11 个类别中的 144 个工具

处理流程

AudacityMCP 为常见音频任务提供 9 个一键处理流程。每个流程都针对录音质量不佳的音频设计，确保安全——绝不会以危险的方式提高音量。处理流程会清理并改善音频；如果需要，你可以之后再手动调整响度。

处理流程的工作方式

1. 告诉 AI 你的需求（例如：“清理这段播客”）
2. AI 选择合适的处理流程并启动
3. 处理流程在后台运行——你会收到一个 job_id
4. 每隔 15–30 秒调用 check_pipeline_status 以查看进度
5. 完成后，Audacity 中会弹出提示

安全规则： 如果峰值过高，处理流程只会降低峰值，绝不会提高响度。如果你想达到指定的 LUFS 目标（例如 Spotify 的 -14），请先确认结果符合要求，再让 AI 运行 loudness_normalize。

处理流程参考

auto_analyze_audio — 处理前先分析

测量音频并推荐最佳处理流程。如果不确定该怎么做，请先运行此工具。

You: "Analyze this audio"
→ Returns: peak level, noise floor, clipping status, recommended pipeline

auto_cleanup_audio — 仅安全清理

清理噪声和瑕疵，完全不改变响度。适用于音量电平已经合适的情况。

You: "Just clean up the noise, don't change the volume"
→ DC offset removal → HPF 80Hz → noise reduction → click removal (optional)

auto_cleanup_podcast — 播客 / 配音

为口语内容提供专业的广播级处理。

You: "Clean up this podcast recording"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 3:1 → safe loudness check

auto_audiobook_mastering — 有声书（ACX/Audible）

针对有声书发行的 ACX 要求进行处理。

You: "Master this for ACX / Audible"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 2.5:1 → safe loudness check → peak cap -3dB

auto_cleanup_interview — 访谈 / 对话

轻度处理对话音频，保留自然的动态效果。

You: "Clean up this interview recording"
→ DC offset → HPF 80Hz → noise reduction 8dB → compression 2.5:1 → safe loudness check

auto_cleanup_vocal — 演唱 / 录音室人声

针对人声录音进行调校，通过增强存在感的均衡处理提升清晰度。

You: "Process this vocal recording"
→ DC offset → HPF 100Hz → noise reduction 10dB → compression 3:1 → presence EQ (+3dB treble, -1dB bass) → safe loudness check

auto_cleanup_live — 现场 / 外录 / 嘈杂录音

针对嘈杂环境进行强力清理。用于分析的前 0.5 秒必须是环境噪声。

You: "This is a noisy live recording, clean it up"
→ DC offset → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1 → safe loudness check

auto_master_music — 音乐母带处理

针对不同流派调校的母带处理，包含 6 个预设：edm、hiphop、rock、pop、classical、acoustic。

You: "Master this hip-hop track"
→ HPF 30Hz → click removal → compression 2:1 → bass +3dB treble +1dB → safe loudness check

You: "Master this for a classical album"
→ HPF 30Hz → click removal → compression 1.3:1 (very gentle) → no EQ → safe loudness check

auto_lofi_effect — 创意低保真 / 复古效果

添加温暖、复古的低保真音色。预设：light、medium、heavy。

You: "Give this a lo-fi vibe"
→ HPF → LPF (muffled highs) → bass/treble warmth → compression 2:1 → safe loudness check

使用处理管线后：调整响度

处理管线会有意保持响度不变（仅在峰值发生削波时才会降低响度）。如需达到流媒体平台的目标响度：

You: "Now normalize this to -14 LUFS for Spotify"
→ AI uses loudness_normalize tool with lufs_level=-14

You: "Normalize to -16 LUFS for podcast"
→ AI uses loudness_normalize tool with lufs_level=-16

为什么不自动处理？ LUFS 标准化可能会将音量较低或录制效果不佳的音频提升 10-20 dB，导致声音失真。将清理与响度调整分开，您就可以在最终调整响度前检查处理结果。

本地转录（实验性功能）

此功能处于实验阶段，需要单独设置。其他功能均可直接使用。

由 faster-whisper 提供支持 — 完全离线运行，音频不会离开您的设备：

• 5 种模型尺寸：tiny、base、small、medium、large-v3
• 转录完整音频或仅转录选中片段
• 导出为 SRT、VTT 或纯文本字幕
• 在每个语音片段处自动添加 Audacity 标签
• 自动检测语言，或指定 99 种以上语言

首次使用前需要设置： 安装步骤请参阅转录设置。

想要启用 GPU 加速（速度提升 10-20 倍）？ 运行 audacity-mcp-setup-gpu — 或下载 setup_gpu.bat/setup_gpu.sh，然后双击/运行；如果您不想使用终端，可以选择这种方式。该脚本会检测您的 GPU、安装所需组件，并验证其是否正常运行。仅支持 NVIDIA GPU（转录后端完全不支持 AMD/Intel 显卡和 macOS — 任何 NVIDIA 显卡均可，不要求是 GeForce，只要有 NVIDIA GPU 即可）。没有 NVIDIA GPU？CPU 也能正常工作，只是处理较长文件时速度较慢。

脚本显示运行成功，但转录仍然很慢/仍在使用 CPU？这意味着 Claude Desktop 启动 audacity-mcp 时使用的 Python 环境与脚本刚验证的环境不同 — 请参阅解决方法（手动编辑配置，耗时五分钟）。

新增内容 — v0.1.3

新增 32 个工具（99 → 131）、修复了管线调优问题，并通过 Audacity 实测。

• 新增效果：Reverse、Invert、Repair、AutoDuck、NotchFilter、VocalReduction、AdjustableFade、StudioFadeOut、CrossfadeClips、CrossfadeTracks、ClipFix、SlidingStretch、Tremolo
• 新增编辑功能：Split（原位）、SplitCut、SplitDelete、Disjoin + 将旧的 split 重命名为 edit_split_new
• 新增轨道功能：StereoToMono、MixAndRenderToNew、MuteAll、UnmuteAll、Resample、AlignEndToEnd、AddLabelTrack
• 新增选区功能：CursorToTrackStart/End、CursorToProjectStart/End、SelectCursorToTrackEnd
• 新增项目功能：EditMetadata、ImportMIDI
• 新增标签功能：RegularIntervalLabels
• 管线修复：ACX 峰值上限从 -3.0 调整为 -3.5 dB；实时降噪从 18 调整为 12 dB；播客压缩器参数从 10 ms/1 s 调整为 30 ms/200 ms；访谈释放时间从 1 s 调整为 200 ms
• 错误修复：effect_repair 现在会使用较长的超时时间（Audacity 在选区无效时会显示弹窗）
• 验证：为 AutoDuck、VocalReduction、SlidingStretch、Resample 补充了缺失的范围检查

故障排除

未启用 mod-script-pipe

安装程序会自动启用该功能，但如果没有生效（例如之前从未打开过 Audacity），请手动启用：

1. 打开 Audacity
2. 前往 Edit → Preferences（Windows/Linux）或 Audacity → Preferences（macOS）
3. 点击左侧边栏中的 Modules
4. 将 mod-script-pipe 设置为 Enabled
5. 点击 OK，然后重启 Audacity

连接问题

管线问题

音频质量提示

常见问题

架构

┌──────────────┐     stdio      ┌──────────────┐   named pipe   ┌──────────────┐
│  MCP Client  │◄──────────────►│ AudacityMCP  │◄──────────────►│   Audacity   │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (commands)    │              │
└──────────────┘                └──────────────┘                └──────────────┘
                                       │
                                       ├── audacity_mcp/main.py          (entry point)
                                       ├── audacity_mcp/audacity_client.py (pipe I/O)
                                       ├── audacity_mcp/tool_registry.py  (auto-loader)
                                       └── audacity_mcp/tools/            (11 modules)

关键设计决策

• 命名管道，而非 TCP——通过 Audacity 的 mod-script-pipe 直接进行 IPC。不会暴露网络，也不会发生端口冲突。
• 不使用 exec/eval——每项操作都映射到带输入验证的静态处理程序，不会执行任意代码。
• 跨平台——Windows 通过 ctypes 使用 Win32 API，Unix 使用标准文件 I/O。
• 全面异步——所有工具处理程序都是 async。阻塞式管道 I/O 在执行器池中运行，并支持配置超时时间。
• 安全的处理管道——处理管道会先测量音频，再决定响度。只会降低音量，不会增大音量。
• 动态注册工具——在 audacity_mcp/tools/ 中添加模块并导出 register(mcp) 函数，即可自动发现该模块。

项目结构

AudacityMCP/
├── audacity_mcp/
│   ├── main.py                 # FastMCP server entry point
│   ├── audacity_client.py      # Cross-platform named pipe client
│   ├── tool_registry.py        # Auto-discovers and registers tool modules
│   └── tools/
│       ├── analysis_tools.py   # Audio analysis (contrast, spectrum, beats)
│       ├── cleanup_tools.py    # Noise reduction, mastering, 9 pipelines
│       ├── edit_tools.py       # Cut, copy, paste, split, join, trim
│       ├── effects_tools.py    # Reverb, echo, pitch, EQ, filters
│       ├── generate_tools.py   # Tone, noise, chirp, DTMF generation
│       ├── label_tools.py      # Label management
│       ├── project_tools.py    # Project/file operations
│       ├── selection_tools.py  # Selection and cursor control
│       ├── track_tools.py      # Track management
│       ├── transcription_tools.py  # Whisper-based transcription
│       └── transport_tools.py  # Playback and recording control
├── audacity_mcp_shared/
│   ├── constants.py            # Pipe paths, timeouts, allowed formats
│   ├── error_codes.py          # Typed error codes (pipe/command/validation)
│   └── pipe_protocol.py        # Command formatting and response parsing
├── tests/                      # 60 tests
├── docs/
│   ├── INSTALLATION.md         # Detailed setup guide
│   └── TOOLS.md                # Complete tool reference
└── pyproject.toml

开发

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

添加新工具

1. 在 audacity_mcp/tools/ 中创建模块（或添加到现有模块）
2. 导出 register(mcp: FastMCP) 函数
3. 使用 @mcp.tool() 装饰器定义工具
4. 完成——工具注册表会在启动时自动发现该工具

# audacity_mcp/tools/my_tools.py
from mcp.server.fastmcp import FastMCP
from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode


def register(mcp: FastMCP):
    from audacity_mcp.main import client

    @mcp.tool()
    async def my_custom_effect(intensity: float = 0.5) -> dict:
        """Apply my custom effect to the selected audio."""
        if not 0 <= intensity <= 1:
            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "intensity must be 0-1")
        return await client.execute_long("MyEffect", Intensity=intensity)

完整指南请参阅 CONTRIBUTING.md。

社区

要让它成为每位 Audacity 用户都会使用的工具，光靠一个人的力量还不够。如果你正在使用 AudacityMCP——哪怕只是试用一下——欢迎加入 Discord：分享你的成果、报告故障、提出改进建议，或者与其他使用 AI 驱动音频编辑的人交流。社区的发展始于一个人告诉另一个人这里的存在。如果你认识可能从中受益的人，请把链接发给他们。

支持

如果 AudacityMCP 为你节省了时间，或帮助你完成音频项目，请考虑赞助：

你的支持有助于维护本项目，并让所有人都能免费使用。

招聘 / 咨询

需要为你的产品定制 MCP 服务、原生插件 / IPC 集成，或本地 AI 流水线吗？本仓库及其相关项目——Reaper-MCP、SongForge-MCP——都是此类方案的公开可运行示例。承接合同项目：[email protected]。

文档

• 安装指南 — Windows、macOS 和 Linux 的详细设置说明
• 工具参考 — 全部 144 个工具的完整参考，包含参数和范围
• 基于转录文本的编辑 — 播客、访谈和讲座的工作流指南（基于标签的编辑）
• 参与贡献 — 如何添加工具并参与贡献
• 更新日志 — 版本历史和发行说明

致谢

感谢以下用户报告错误、提出想法并提供反馈，帮助改进本项目：

• @Harsha-Jay-S — 通过对照真实 Audacity 进行测量验证，诊断出 effect_change_pitch/effect_change_speed 错误（#15），并精准找到了根本原因。

许可证

Apache License 2.0 — 详情请见 LICENSE。

由 Daniel Hodgetts 构建 • 𝕏 @daehonz1