内容
# 聊天与音频
[](https://github.com/learningtour/chat-with-audio/actions/workflows/ci.yml)
[](LICENSE)
_ **智能生产** 的一部分。_
聊天驱动的音频增强：与本地的 Claude（桌面版或 Claude 代码）聊天，讨论录音文件，让工具包分析和改进它。本地的 A/B 查看器允许您完美同步地比较原始文件和处理结果 — 既能听也能看。
```
Claude（聊天） ── MCP（标准输入/输出） ──> Python 协调 ──> C++ DSP 核心（pybind11）
│ 网关 · 压缩器 · 限制器 · EQ
├─> AI 降噪（DeepFilterNet，可选）
├─> 分析（LUFS，SNR，嗡鸣，剪切，频谱）
└─> 会话 ──> A/B 查看器（http://127.0.0.1:8471）
```
## 你可以问什么？
- **"分析这个文件：/path/to/recording.wav"** — 指标，分数和问题。
- **"让这个声音更好"** — 自动改进：工具检测语音/音乐并自行选择链（高通滤波，嗡鸣陷波器，降噪，网关，EQ，压缩，响度），并解释每一步。
- **"减少噪音"** — 仅降噪（谱减法或 DeepFilterNet AI）。
- **"提高音量而不失真"** — 响度归一化（BS.1770）带真峰限制器。
- **"在 300 Hz 附近降低 3 dB 并轻度压缩"** — 通过 `apply_chain` 的显式链。
- **"将语音设置为 −6 并平衡音乐"** — `refine_audio`：分割语音/音乐/沉默并运行测量和调整循环，直到达到目标。
- **"仅在有问题的地方修复"** — `smart_edit`：AI 在时间轴上找到问题区域 — 出现和消失的主嗡鸣，暂时升高的噪音（交流，交通），剪切簇，低频隆隆声 — 并在每个区域应用有针对性的微链，带交叉渐入渐出。
- **"保存此为预设" / "像我的播客预设一样处理"** — `save_recipe`，`apply_recipe` 和 `list_recipes`：将一个会话的链保存为命名预设，重用它，并分享。
- **"让它变得更好，花点时间"** — `optimize_audio`：运行多个管道变体并根据客观分数选择最佳结果。
- **"转录此音频"** — `transcribe_audio`（Whisper，[asr] 额外）。
- **"修复剪切和点击"** — `repair_audio`：重建波形并去除点击。
- **"使其听起来像这个参考音频"** — `match_reference`：1/3 倍频程匹配 EQ + 响度匹配。
- **"分割音轨" / "人声增强 3 dB" / "创建卡拉 OK 版本"** — `separate_stems` 和 `rebalance_music`（Demucs，[stems] 额外）。
- **"处理整个文件夹"** — `improve_folder`：批量处理。
- **"显示我更改了什么"** — `view_audio`：一个感知面板，显示 AI 检查的修改。
- **"这个听起来不错 / 这个听起来很差"** — `rate_audio`：训练自己的口味模型。
- **"在 Audition 中设置此项"** — `export_to_audition`：导出音轨和会话文件。
- **"是否符合广播标准？"** — `check_compliance`：根据 EBU R128，ATSC A/85 等标准进行合规性检查。
- **"为欧洲广播制作，48 kHz 24 位"** — `master_for`：根据规范进行母带制作。
- **"润色对话"** — `breath_control`，`deplosive` 和 `duck_music`。
- **"给我区域地图作为标记"** — `export_markers`：将 AI 找到的区域导出为标记。
- **"用环境音填充空白"** — `fill_room_tone`：用文件的环境音填充数字空白。
- **"在 12.3 处有一个椅子刮擦声"** — `spectral_repair`：基于频谱的修复。
- **"将音乐降低到语音下方"** — `duck_music(mode="stems")`：真正的侧链降低。
- **"检查此文件" / "检查此文件夹"** — `qc_report` 和 `qc_folder`：生成质量控制报告。
- **"同步这些录音机"** — `sync_tracks`：同步来自不同设备的音频文件。
- **"打开查看器"** / **"究竟发生了什么变化？"** — A/B 比较。
## 文档
详尽的文档位于 [`docs/`](docs/README.md)： [快速入门](docs/getting-started.md)，完整的 [工具参考](docs/tools.md)， [工作流程手册](docs/workflows.md)（播客，广播交付，电影对话，修复，质量控制）， [交付合规性](docs/compliance.md)， [智能区域](docs/smart-regions.md)， [预设](docs/recipes.md) 和 [架构](docs/architecture.md)。
## 安装（macOS）
需要： [uv](https://docs.astral.sh/uv/)，ffmpeg（`brew install ffmpeg`），Xcode 命令行工具。Python 3.11 由 uv 自行获取。
```bash
cd chat-with-audio
uv sync --all-extras # 构建 C++ 核心并安装所有内容（包括 AI 降噪）
uv run pytest # 109 个测试
uv run python scripts/mcp_smoke.py # MCP 烟雾测试
```
`uv sync`（不带 `--all-extras`）安装基本内容，不包括 torch/DeepFilterNet；工具会自动降级为谱减法。
## 注册 Claude（和 Codex）
- **Claude 代码**：位于项目文件夹中的 `.mcp.json`（在此文件夹中自动工作）。
- **Claude 桌面版**：在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中输入 `chat-with-audio`。安装后重启 Claude 桌面版；工具将出现在“chat-with-audio”下。
- **Codex CLI/app**：通过 `codex mcp add chat-with-audio -- <uv-path> run --directory <project-folder> chat-with-audio-mcp` 注册为全局 MCP 服务器（使用 `codex mcp list` 验证）。与 30 个工具，相同会话和查看器。
注意：在运行 `uv sync --all-extras` 之前，首次启动服务器可能会超时。
## 查看器
`open_viewer`（或 `uv run ait viewer`）在 <http://127.0.0.1:8471> 启动。空格键播放，**a/b = 在原始文件和处理结果之间切换**，**r = 残留量**（您准确地听到处理更改了什么 — 理想的伪影检查），同时保持同步播放。点击波形图以跳转。更改端口请使用 `AIT_VIEWER_PORT` 环境变量。
波形图下方是一个时间轴：一个内容通道（语音/音乐/沉默）和一个干预通道，显示智能编辑会话中哪里出现了问题 — 点击一个区域并使用 **r** 听取被删除的内容。
会话存储在 `~/AudioImprove/sessions/`（可覆盖：`AIT_SESSIONS_DIR`），每个会话包含原始文件，结果，分析，链 + 基本原理，时间轴，波形图和频谱图。
## 预设
预设是一个保存的处理链，作为一个小型 JSON 文件 — 可重用和共享的。内置预设（从真实会话中提炼）随软件包一起提供；您自己的预设存储在 `~/AudioImprove/recipes/`（可覆盖：`AIT_RECIPES_DIR`）。在听起来不错的会话后说“将此保存为我的播客预设”，在新文件中应用它，并与任何人分享 JSON 文件 — `apply_recipe` 也接受文件路径。
## Windows
1. 安装 [uv](https://docs.astral.sh/uv/)，ffmpeg（`winget install ffmpeg`）和 **Visual Studio 构建工具**（C++ 工作负载）以构建本地 DSP 核心。如果没有构建工具，一切都可以在纯 Python 中工作，但 C++ 构建步骤会软失败。
2. 在项目文件夹中运行 `uv sync --all-extras`（DeepFilterNet 提供 win_amd64 轮）。
3. 在 `%APPDATA%\Claude\claude_desktop_config.json` 中注册，使用 `uv.exe` 和项目文件夹的完整路径（与这里的 `.mcp.json` 相同）。
## 架构
| 层 | 位置 | 角色 |
|---|---|---|
| C++ DSP 核心 | `cpp/` | 双二次 EQ（RBJ），噪声门，软膝盖压缩器，预测限幅器；通过 pybind11 暴露为 `chat_with_audio._dsp` |
| DSP 调度 | `src/chat_with_audio/dsp/` | 本地 ↔ scipy 备用，谱减法（`spectral_nr.py`），DeepFilterNet（`ai_nr.py`） |
| 分析 | `analysis.py` | LUFS/LRA（pyloudnorm），真峰值，SNR，噪声底限，嗡鸣，剪切，频谱，分数 + 问题 |
| 决策逻辑 | `improve.py` | 语音/音乐检测，规则 → 链 + 基本原理 |
| 分割 | `segments.py` | 语音/音乐/沉默时间轴（级别 Otsu + 语音调制） |
| 智能区域 | `regions.py` | 窗口化问题检测器（嗡鸣/噪音/剪切/boom）+ 每个区域的微链，带交叉渐入渐出 |
| 预设 | `recipes.py` | 保存的链作为可共享的 JSON；内置预设 + `~/AudioImprove/recipes/` |
| 合规性 | `compliance.py` | 交付规范（EBU/ATSC/Netflix/流媒体/ACX）+ 通过/失败检查 |
| 对话套件 | `dsp/dialogue.py` | 呼吸控制，爆破修复，音乐床减淡 |
| DAW 标记 | `markers.py` | 区域映射 → Audition CSV / Audacity 标签 / JSON |
| 精炼循环 | `refine.py` | 迭代测量 → 调整（语音峰值，平衡，暂停底限），带有 Whisper 保护 |
| 优化 | `optimize.py` | 变体竞赛，根据可懂度和目标进行评分 |
| 可懂度 | `asr.py` | Whisper 转录 + 单词保留（[asr] 额外） |
| 去混响 | `dsp/dereverb.py` | ClearVoice MossFormer2 48 kHz，仅限语音段（[enhance] 额外） |
| 链 | `chain.py` | 步骤注册表（包括均衡器，智能降噪），响度归一化 |
| MCP 服务器 | `server.py` | 30 个工具通过 stdio（FastMCP） |
| 查看器 | `viewer/` | 标准库 http.server + Web Audio A/B 播放器 |
响度目标：语音 −16 LUFS / TP −1.5 dBTP，音乐 −14 LUFS / TP −1.0 dBTP。
## 版本固定（刻意）
- **Python 3.11** 和 **numpy < 2.0**：DeepFilterNet 0.5.x 仅提供构建到 cp311 并需要 numpy 1.x。
- **torch/torchaudio < 2.9**：DeepFilterNet 导入 `torchaudio.backend`，已在 torchaudio 2.9 中删除。
更改 C++ 代码后：`uv sync --reinstall-package chat-with-audio`。
