voicebox-voice-mcp-agent

Voicebox 是一个本地优先的 AI 语音工作室，把语音输入与语音输出整合在同一个 TypeScript/Rust 应用中。默认情况下所有推理都在本机硬件上运行，音频不会离开你的设备，除非显式配置。

用途它面向需要在本机完成语音合成、声音克隆、听写以及让智能体调用语音能力的场景。既可作为桌面应用使用，也提供 Web UI 与 REST/MCP 接口。

主要能力

七种 TTS 引擎：Qwen3-TTS、Qwen CustomVoice、LuxTTS、Chatterbox Multilingual/Turbo、HumeAI TADA、Kokoro。
声音克隆：从短参考样本进行零样本克隆。
全局听写：系统级热键，转录结果粘贴到当前焦点输入框。
MCP HTTP 服务器：在 /mcp 暴露工具，支持智能体驱动的语音工作流。
23 种语言的多语言合成。
音效：音高、混响、延迟、合唱、压缩、滤波。
本地 LLM 精修：内置 Qwen3 用于转录清理。
技术栈：Bun monorepo、TypeScript、Tauri 2（Rust）、React 18、Zustand、TanStack Router、Vite。

安装与运行前置依赖：

安装 Bun：curl -fsSL https://bun.sh/install | bash
安装 Rust（用于 Tauri 桌面构建）：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
安装 FFmpeg（音频处理）：macOS 使用 brew install ffmpeg；Ubuntu/Debian 使用 sudo apt install ffmpeg；Windows 从 ffmpeg.org 下载。

快速设置：

git clone https://github.com/jamiepine/voicebox.git
cd voicebox
just setup
just dev

开发模式：

仅 Web UI（http://127.0.0.1:5173）：bun run dev:web
Tauri 桌面开发：bun run dev
生产构建：bun run build
桌面发布构建：just build:desktop

配置在项目根目录创建 .env，可设置：

VOICEBOX_HOST=127.0.0.1
VOICEBOX_PORT=17493
VOICEBOX_CORS_ORIGINS=http://localhost:3000,http://localhost:5173
LOG_LEVEL=info
HF_TOKEN=your_huggingface_token_here（用于受限模型）
可选的 Redis 持久化缓存（用于 Web 部署）：VOICEBOX_REDIS_ENABLED=false、VOICEBOX_REDIS_URL=redis://127.0.0.1:6379、VOICEBOX_REDIS_KEY_PREFIX=voicebox:

MCP 客户端配置：创建 .mcp.json，内容为 {"mcpServers": {"voicebox": {"url": "http://127.0.0.1:17493/mcp", "description": "Voicebox voice synthesis and dictation server"}}}。

使用方式 REST API：服务运行时在 http://127.0.0.1:17493 暴露 REST API。

生成语音：向 /generations 发送 POST，请求体包含 text、profileId，可选 engine 与 effects（音效类型包括 pitch、reverb、delay、chorus、compression，参数为数值字典）。
流式进度：向 /generations/stream 发送 POST，通过 Server-Sent Events 读取进度与状态。
声音克隆：向 /voices/clone 发送 POST，使用 FormData 提交 name、reference（参考音频文件）与 engine，返回 voiceId。

MCP 集成：MCP 服务器运行在 http://127.0.0.1:17493/mcp，暴露工具供智能体调用，例如 synthesize_speech（参数 text、profile_id，可选 engine）、clone_voice（参数 name、reference_path，可选 engine）、start_dictation（可选 language）。可通过向 /mcp/execute 发送 POST 调用工具。

扩展与内部结构

TTS 引擎接口：app/src/services/tts/types.ts 定义 TTSEngine（name、synthesize、可选 clone、supportedLanguages）与 SynthesisOptions（voiceId、language、speed、pitch）。可在 app/src/services/tts/registry.ts 注册自定义引擎。
平台适配器：app/src/platform/types.ts 定义 Platform 接口（文件读写、音频采集、桌面热键、更新检查），桌面实现基于 Tauri。
状态管理：使用 Zustand，示例见 app/src/stores/voice.ts，管理语音配置（profiles、activeProfileId 及增删改查）。
全局听写热键：桌面端通过 Tauri 全局快捷键插件注册（默认 CommandOrControl+Shift+D），触发后由 Rust 后端完成音频采集、Whisper STT 推理并模拟粘贴到焦点应用。

适用场景

在本机进行语音合成与多语言配音。
用短样本克隆声音并配合音效生成音频。
通过系统热键进行全局听写，把语音转成文字粘贴到任意输入框。
让 MCP 智能体调用语音合成、克隆与听写工具。
在本地对转录文本进行 LLM 清理。

限制

默认本地推理，音频不离开本机，除非显式配置。
部分模型可能受 HuggingFace 门控限制，需要 HF_TOKEN。
全局热键与更新检查等能力仅在桌面端可用。
关于收费、价格、平台支持范围与具体效果，资料中暂未提供。

技能介绍