E2E Voice - 端到端语音对话系统

C++17 端到端智能语音对话系统，集成 ASR（语音识别）、LLM（大语言模型）、TTS（语音合成）、VAD（语音活动检测）和 AEC（全双工回声消除）。

English

[!IMPORTANT] 分支说明

• master 分支：保留原始单体架构代码，不再更新
• refactor 分支：当前活跃开发分支，后续所有开发基于此分支

重构改进（master → refactor）

基于 288 个文件变更（净减少 ~136 万行代码），核心改进如下：

1. 模块化架构 — 6 个核心模块（audio / stt / tts / vad / llm / mcp）拆分为独立 Git 子仓库（submodule），可单独开发、测试、复用
2. 全双工语音对话 — 新增 WebRTC AEC 回声消除管道（voice_chat_aec），支持 Barge-in 打断，替代原有半双工方案
3. 去除冗余代码 — 移除内嵌的 third_party（cppjieba、cpp-pinyin、cpp-mcp 等），改用 CMake FetchContent 按需拉取
4. 统一 API 规范 — 每个模块提供标准化的 *_api.hpp 公共头文件和 API.md 文档
5. Python 绑定 — audio / stt / tts / vad 提供 pybind11 接口，支持 pip install -e .
6. 清理遗留代码 — 移除旧的 Python 脚本、遗留 C++ 示例、build.sh 等

特性

• 全双工对话 — WebRTC AEC 回声消除 + 噪声抑制，支持 Barge-in 打断
• 离线语音识别 — SenseVoice ONNX，支持中/英/日/韩/粤多语言
• 多后端语音合成 — Matcha-TTS（中/英/中英混合）+ Kokoro（多音色）
• LLM 集成 — Ollama 本地推理 / OpenAI 兼容云端 API，流式输出
• MCP 工具调用 — 通过 Model Context Protocol 扩展 LLM 能力（可选）
• 模块化架构 — audio / stt / tts / vad / llm / mcp 独立模块，可单独使用
• Python 绑定 — audio / stt / tts / vad 提供 pybind11 Python 接口

架构

全双工 AEC 管道

模块化架构

依赖

sudo apt install gcc g++ cmake pkg-config \
  libportaudio-dev libsndfile1-dev \
  libcurl4-openssl-dev libfftw3-dev \
  libssl-dev espeak-ng libabsl-dev

ONNX Runtime 需手动安装，参见 ONNX Runtime Releases：

wget https://github.com/microsoft/onnxruntime/releases/download/v1.20.0/onnxruntime-linux-x64-1.20.0.tgz
tar -xzf onnxruntime-linux-x64-1.20.0.tgz
sudo cp -r onnxruntime-linux-x64-1.20.0/include/* /usr/local/include/
sudo cp -r onnxruntime-linux-x64-1.20.0/lib/* /usr/local/lib/
sudo ldconfig

brew install gcc cmake pkg-config \
  portaudio libsndfile curl fftw \
  onnxruntime espeak openssl abseil

本地 LLM（Ollama）：

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen2.5:0.5b

编译与运行

编译

git clone --recursive https://github.com/muggle-stack/e2e_Voice.git
cd e2e_Voice
mkdir -p build && cd build
cmake .. && make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)

CMake 选项：

# 启用 MCP 工具调用
cmake -DUSE_MCP=ON .. && make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)

注意： AEC 需要先编译 WebRTC 模块：cd modules/webrtc-audio-processing && meson build && ninja -C build

运行

./build/bin/voice_chat_aec                                     # 默认配置
./build/bin/voice_chat_aec --tts kokoro --model qwen2.5:7b     # Kokoro TTS + 更大模型
./build/bin/voice_chat_aec -l                                  # 列出音频设备
./build/bin/voice_chat_aec --mcp-config mcp.json               # 启用工具调用
./build/bin/voice_chat_aec --llm-url https://api.example.com/v1/chat/completions  # 云端 LLM

运行时选项

MCP 工具调用（可选）

通过 MCP（Model Context Protocol） 扩展 LLM 的工具调用能力。编译时需启用 USE_MCP=ON。

快速体验：

# 安装 Python 依赖
pip install mcp starlette uvicorn psutil flask

# 一键启动示例 MCP 服务（注册中心 + Calculator + TimeService + SystemMonitor）
cd modules/mcp/examples && bash start_all_services.sh

# 启动语音对话，连接注册中心自动发现工具
./build/bin/voice_chat_aec --mcp-config modules/mcp/examples/config_registry.json

编辑 config_registry.json 可切换 MCP 工具调用使用的 LLM 后端：

{
  "backend": "ollama",                    // "ollama"（本地）或 "llama"（OpenAI 兼容 API）
  "url": "http://localhost:11434",        // LLM API 地址
  "model": "qwen2.5:7b",                 // 模型名称
  "registry_url": "http://127.0.0.1:9000/mcp/services"
}

自定义扩展：

用户可以编写自己的 MCP 服务并注册到注册中心（默认端口 9000），voice_chat_aec 会自动发现新工具，无需重启：

1. 用 FastMCP 编写 Python 服务
2. 启动时注册到注册中心：--registry http://127.0.0.1:9000
3. 语音对话中 LLM 即可调用新工具

配置文件格式和传输方式详见 MCP 模块文档。

组件演示

各模块提供独立的可执行演示：

./build/bin/stt_test audio.wav       # 文件语音识别
./build/bin/simple_demo --text "你好" # TTS 语音合成
./build/bin/vad_simple_demo          # VAD 语音活动检测
./build/bin/audio_demo -l            # 音频设备列表

Python 绑定

4 个核心模块提供 pybind11 Python 接口：

cd modules/audio/python && pip install -e .   # evo_audio
cd modules/stt/python   && pip install -e .   # evo_asr
cd modules/tts/python   && pip install -e .   # evo_tts
cd modules/vad/python   && pip install -e .   # evo_vad

详细用法参见各模块 README。

模型缓存

首次运行时自动下载到 ~/.cache/：

~/.cache/
├── sensevoice/                          # ASR (SenseVoice ONNX)
├── matcha-tts/
│   ├── matcha-icefall-zh-baker/         # 中文 TTS (22050Hz)
│   ├── matcha-icefall-en_US-ljspeech/   # 英文 TTS (22050Hz)
│   ├── matcha-icefall-zh-en/            # 中英混合 TTS (16000Hz)
│   ├── vocos-22khz-univ.onnx           # Vocoder (中文/英文)
│   └── vocos-16khz-univ.onnx           # Vocoder (中英混合)
└── silero_vad.onnx                      # VAD (Silero)

许可证

MIT License — 详见 LICENSE

致谢

• ONNX Runtime — 高性能推理引擎
• llama.cpp — 高性能 LLM 推理引擎
• Ollama — 本地 LLM 运行与管理
• SenseVoice — 语音识别模型
• Matcha-TTS — 语音合成模型
• Kokoro — 多音色语音合成
• Vocos — 声码器
• Silero VAD — 语音活动检测
• WebRTC Audio Processing — 回声消除 / 噪声抑制
• PortAudio — 跨平台音频 I/O
• cppjieba — C++ 中文分词
• cpp-pinyin — 中文转拼音
• espeak-ng — 英文音素化
• nlohmann/json — JSON 库
• pybind11 — Python 绑定
• dengcunqin — 中英文 Matcha 模型