> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/jamiepine/voicebox) · [上游 README](https://github.com/jamiepine/voicebox/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Voicebox
开源 AI 语音工作室。
克隆任意声音。生成语音。向任意应用听写。用你拥有的声音与智能体对话。
完整的语音输入/输出（voice I/O）技术栈，在本地机器上运行。
voicebox.sh •
Docs •
Download •
Features •
API •
Troubleshooting
点击上方图片，在 voicebox.sh 观看演示视频
## 什么是 Voicebox？
Voicebox 是一款**本地优先（local-first）的 AI 语音工作室**——在一个应用中免费开源地替代 **ElevenLabs** 和 **WisprFlow**。只需几秒音频即可克隆声音，通过 7 款 TTS 引擎以 23 种语言生成语音，用全局快捷键向任意文本框听写，并为任意支持 MCP 的 AI 智能体指定你想要的声音。
两家云端 incumbent 分别占据语音 I/O 循环的两端——ElevenLabs 负责输出，WisprFlow 负责输入。Voicebox 两者兼顾，通过内置本地 LLM 进行润色和按配置 persona 定制，并将整套流程运行在你的机器上。
- **完全隐私** — 模型、语音数据和录音绝不会离开你的机器
- **7 款 TTS 引擎** — Qwen3-TTS、Qwen CustomVoice、LuxTTS、Chatterbox Multilingual、Chatterbox Turbo、HumeAI TADA 和 Kokoro
- **声音克隆与预设声音** — 从参考样本零样本克隆，或通过 Kokoro 和 Qwen CustomVoice 使用 50+ 款精选预设声音
- **23 种语言** — 从英语到阿拉伯语、日语、印地语、斯瓦希里语等
- **后处理效果** — 变调、混响、延迟、合唱、压缩和滤波器
- **富有表现力的语音** — 通过 Chatterbox Turbo 使用 `[laugh]`、`[sigh]`、`[gasp]` 等副语言（paralinguistic）标签；通过 Qwen CustomVoice 以自然语言控制表达方式
- **无限长度** — 针对脚本、文章和章节自动分块并交叉淡入淡出
- **Stories 编辑器** — 用于对话、播客和叙事的多轨时间线
- **语音输入** — 全局听写快捷键，支持按住说话和切换模式，macOS 上经无障碍验证的自动粘贴，每个文本框均有应用内麦克风，基于 Whisper 的 STT
- **智能体语音输出** — 一次工具调用（`voicebox.speak`），任意支持 MCP 的智能体（Claude Code、Cursor、Cline）即可用你克隆的声音与你对话
- **声音人格（Voice personalities）** — 为任意声音配置附加自由格式 persona，然后通过内置本地 LLM 进行 Compose、Rewrite 或 Respond——智能体也可通过 MCP 调用相同模式
- **API 优先** — REST API 加内置 MCP 服务器，将语音 I/O 集成到你自己的应用和智能体中
- **原生性能** — 基于 Tauri（Rust）构建，而非 Electron
- **随处运行** — macOS（MLX/Metal）、Windows（CUDA）、Linux、AMD ROCm、Intel Arc、Docker
---
## 下载
| Platform | Download |
| --------------------- | ------------------------------------------------------ |
| macOS (Apple Silicon) | [Download DMG](https://voicebox.sh/download/mac-arm) |
| macOS (Intel) | [Download DMG](https://voicebox.sh/download/mac-intel) |
| Windows | [Download MSI](https://voicebox.sh/download/windows) |
| Docker | `docker compose up` |
> **[查看全部二进制文件 →](https://github.com/jamiepine/voicebox/releases/latest)**
> **Linux** — 预编译二进制文件尚未提供。请参阅 [voicebox.sh/linux-install](https://voicebox.sh/linux-install) 了解从源码构建的说明。
> **遇到问题？** 请参阅[故障排除指南](docs/content/docs/overview/troubleshooting.mdx)，了解常见的安装、生成、模型下载和 GPU 问题。
---
## 功能
### 多引擎声音克隆
七款 TTS 引擎各有优势，可按每次生成切换：
| Engine | Languages | Strengths |
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Qwen3-TTS** (0.6B / 1.7B) | 10 | 高质量多语言克隆，支持表达指令（如 "speak slowly"、"whisper"） |
| **Qwen CustomVoice** | 10 | 9 款精选预设声音，支持自然语言表达控制——无需参考音频 |
| **LuxTTS** | English | 轻量（约 1GB VRAM），48kHz 输出，CPU 上 150 倍实时速度 |
| **Chatterbox Multilingual** | 23 | 最广语言覆盖——阿拉伯语、丹麦语、芬兰语、希腊语、希伯来语、印地语、马来语、挪威语、波兰语、斯瓦希里语、瑞典语、土耳其语等 |
| **Chatterbox Turbo** | English | 快速 350M 模型，支持副语言情感/音效标签 |
| **TADA** (1B / 3B) | 10 | HumeAI 语音-语言模型——700 秒以上连贯音频，文本-声学双对齐 |
| **Kokoro** | 8 | 50 款精选预设声音，82M 微型模型，CPU 推理速度快 |
### 情感与副语言标签
仅 **Chatterbox Turbo** 会解析 `[laugh]` 和
`[sigh]` 等副语言标签。Qwen3-TTS、LuxTTS、Chatterbox Multilingual 和 HumeAI TADA 会将其字面朗读为文本。
选择 **Chatterbox Turbo** 后，在文本输入框中输入 `/` 即可打开标签插入器，在语音中内联添加表现力标签：
`[laugh]` `[chuckle]` `[gasp]` `[cough]` `[sigh]` `[groan]` `[sniff]` `[shush]` `[clear throat]`
### 后处理效果
8 种音频效果，由 Spotify 的 `pedalboard` 库驱动。生成后应用，实时预览，可构建可复用预设。
| Effect | Description |
| ---------------- | --------------------------------------------- |
| Pitch Shift | 上下最多 12 个半音 |
| Reverb | 可配置房间大小、阻尼、湿/干混合 |
| Delay | 可调时间、反馈和混合比的回声 |
| Chorus / Flanger | 调制延迟，营造金属感或丰厚质感 |
| Compressor | 动态范围压缩 |
| Gain | 音量调节（-40 至 +40 dB） |
| High-Pass Filter | 去除低频 |
| Low-Pass Filter | 去除高频 |
内置 4 种预设（Robotic、Radio、Echo Chamber、Deep Voice），并支持自定义预设。效果可按配置文件（profile）分别设为默认项。
### 无限生成长度
文本会在句子边界自动切分，每个分块独立生成，再通过交叉淡入淡出拼接在一起。适用于所有引擎。
- 可配置自动分块上限（100–5,000 字符）
- 交叉淡入淡出滑块（0–200ms），实现平滑过渡
- 最大文本长度：50,000 字符
- 智能切分会识别缩写、CJK 标点以及 `[tags]`
### 生成版本
每次生成均支持多版本，并带有来源（provenance）追踪：
- **Original（原始）** — 干净的 TTS 输出，始终保留
- **Effects versions（效果版本）** — 从任意源版本应用不同的效果链
- **Takes（重录）** — 使用新种子重新生成以产生变化
- **Source tracking（来源追踪）** — 每个版本都会记录其谱系
- **Favorites（收藏）** — 为生成结果加星标，便于快速访问
### 异步生成队列
生成过程不阻塞界面。提交后即可立即开始输入下一条。
- 串行执行队列，避免 GPU 争用
- 实时 SSE 状态流式推送
- 失败的生成可重试
- 因崩溃产生的陈旧生成任务，在启动时会自动恢复
### 语音配置文件管理
- 从音频文件创建配置文件，或在应用内直接录制
- 导入/导出配置文件，便于分享或备份
- 多样本支持，提升克隆质量
- 每个配置文件可设置默认效果链
- 通过描述和语言标签进行组织管理
### Stories 编辑器
面向对话、播客和叙事内容的多声部时间线编辑器。
- 多轨编排，支持拖放
- 内联音频裁剪与分割
- 自动播放，播放头同步
- 每个轨道片段可固定版本
### 全局听写与语音输入
语音 I/O 循环的另一半。在系统任意位置按住快捷键，说话，松手 — 在 macOS 上，转写文本会直接粘贴到当前聚焦的文本框。或在任意 Voicebox 文本输入框点击麦克风，直接在应用内听写。
- **可配置组合键绑定** — 按住说话与点按切换两种组合键，均可在应用内组合键选择器中重新绑定。按住 push-to-talk 期间点按 `Space`，可在不中断音频的情况下升级为切换会话
- **目标感知粘贴（macOS）** — 经无障碍（accessibility）校验后注入到聚焦文本框，并原子化保存/恢复剪贴板，避免覆盖你的剪贴板内容
- **首次运行权限引导** — 应用内门禁会引导你完成 macOS 无障碍与输入监控授权，并提供直达系统设置的深链接
- **应用内麦克风按钮** — 每个 Voicebox 文本输入框均有：生成表单、配置文件描述、故事标题等所有可输入处
- **LLM 润色** — 粘贴前可选清理“嗯”、口吃和说错开头
- **屏幕悬浮条（pill）** — 浮动叠加层展示 `recording`、`transcribing`、`refining` 与 `speaking` 状态。与智能体对你说话时使用的同一条 pill 一致，因此语音循环双向共用同一心智模型
### 语音转文字（Speech-to-Text）
Voicebox 使用 OpenAI Whisper 进行转写 — 与听写、Captures 标签页以及 `/transcribe` API 共用同一模型。根据平台在 MLX（Apple Silicon）或 PyTorch（CUDA / ROCm / DirectML / CPU）上运行。
| Size | Notes |
| ----------------------------- | -------------------------------------------------- |
| Base / Small / Medium / Large | 标准 Whisper 质量阶梯 |
| Turbo | 比 Whisper Large 快约 8 倍，质量损失极小 |
更多引擎（Parakeet v3、Qwen3-ASR）已在规划中 — 见 [Roadmap](#roadmap)。
### Captures（采集）
每次听写、应用内录制和上传的音频文件都会进入 Captures 标签页 — 原始音频与转写文本配对保存，始终保留。
- **重放、重新转写、润色** — 可用任意 Whisper 尺寸重新运行 STT，或将原始转写文本通过本地 LLM 以不同标志重跑（填充词清理、自我纠正移除、技术术语保留）
- **内联编辑** — 调整转写文本，失焦时保存
- **作为语音配置文件播放** — 一键将任意采集转为克隆语音朗读
- **提升为语音样本** — 将采集的音频 + 转写文本用作任意语音配置文件的参考样本
- **本地采集存储** — 原始音频与转写文本保存在 Voicebox 数据目录，设置中提供文件夹快捷方式
### 智能体语音输出
每个智能体都有声音。一次工具调用，任意支持 MCP 的智能体即可用你克隆的语音对你说话 — 任务完成、提问、通知等。听写时显示的同一条 pill 在智能体说话时也会出现，因此你始终能看到机器正在输出什么。
```ts
// In any MCP-aware agent:
await voicebox.speak({
text: "Deploy complete.",
profile: "Morgan",
});
```
同时也以 `POST /speak` 形式暴露，供非 MCP 语音场景使用 — ACP、A2A、shell 脚本、自定义 harness 等。
- **双向 pill** — `recording`、`transcribing`、`refining` 与 `speaking` 均为同一操作系统级叠加层的不同状态，听写与智能体语音共用同一界面
- **按智能体绑定语音** — 在 **Settings → MCP** 中，将 Claude Code 固定为 Morgan、Cursor 固定为 Scarlett，无需看屏幕即可分辨谁在说话。各客户端的 `last_seen_at` 时间戳可确认安装是否真正生效
- **始终可见** — 无静默后台 TTS；智能体发起的每次 speak 都会在全程显示带有语音配置文件名称的 pill
- **HTTP + stdio 传输** — 在 Claude Code / Cursor / Windsurf / VS Code MCP 中安装为 URL，或让仅支持 stdio 的客户端指向捆绑的 `voicebox-mcp` 二进制
### 语音个性（Voice Personalities）
可为任意语音配置文件附加自由格式的个性描述 — 这个声音是谁、如何说话、关心什么。设置个性后，生成框会出现两个操作，由捆绑的 Qwen3 LLM 完全在本地驱动。
- **Compose（创作）** — 洗牌按钮，向文本区域放入一条符合角色设定的新台词；可编辑后朗读，或再次点击换一版
- **Speak in character（角色化朗读）** — 开关将你的输入文本先经个性 LLM 改写成该角色口吻，再进行 TTS
智能体也可通过 MCP 走同一路径：向 `voicebox.speak` 传入 `personality: true`，将工具变为 文本输入 → 个性 LLM → TTS 流水线。同一 LLM 也支撑听写润色步骤 — 应用内一个 LLM、一个模型缓存、一份 GPU 显存占用。
**本地 LLM 选项：** Qwen3 0.6B / 1.7B / 4B，与 TTS 运行时共享（Apple Silicon 用 MLX，其他平台用 PyTorch）。
用例：智能体开发循环（听写提问、用克隆语音听答案）、游戏与叙事工具的交互角色、为无法以原声说话的人提供语音辅助。
### 模型管理
- 按模型卸载以释放 GPU 显存，无需删除已下载文件
- 通过 `VOICEBOX_MODELS_DIR` 自定义模型目录
- 模型文件夹迁移，带进度追踪
- 下载取消/清理 UI
### GPU 支持
| Platform | Backend | Notes |
| ------------------------ | -------------- | ---------------------------------------------- |
| macOS (Apple Silicon) | MLX (Metal) | 借助 Neural Engine，速度约为 4–5 倍 |
| Windows / Linux (NVIDIA) | PyTorch (CUDA) | 应用内自动下载 CUDA 二进制 |
| Linux (AMD) | PyTorch (ROCm) | 自动配置 HSA_OVERRIDE_GFX_VERSION |
| Windows (any GPU) | DirectML | 通用 Windows GPU 支持 |
| Intel Arc | IPEX/XPU | Intel 独立 GPU 加速 |
| Any | CPU | 全平台可用，速度较慢 |
---
## API
Voicebox 提供 REST API，便于将语音 I/O 集成到你自己的应用与智能体中。
```bash
# Generate speech
curl -X POST http://127.0.0.1:17493/generate \
-H "Content-Type: application/json" \
-d '{"text": "Hello world", "profile_id": "abc123", "language": "en"}'
# Agent voice output — any app or script can speak in a cloned voice
curl -X POST http://127.0.0.1:17493/speak \
-H "Content-Type: application/json" \
-H "X-Voicebox-Client-Id: my-script" \
-d '{"text": "Deploy complete.", "profile": "Morgan"}'
# Transcribe an audio file
curl -X POST http://127.0.0.1:17493/transcribe \
-F "audio=@recording.wav" \
-F "model=whisper-turbo"
# List voice profiles
curl http://127.0.0.1:17493/profiles
```
`POST /speak` 接受 `profile` 作为名称（不区分大小写）或 id，并通过与 MCP 工具相同的优先级进行解析：显式参数 → 按客户端绑定 → `capture_settings.default_playback_voice_id`。
### MCP 服务器
Voicebox 内置 **Model Context Protocol（MCP）** 服务器，任何支持 MCP 的智能体（Claude Code、Cursor、Windsurf、Cline、VS Code MCP 扩展）都可以进行语音合成、转录，以及浏览录制内容和配置文件。
**Claude Code 一行配置：**
```
claude mcp add voicebox \
--transport http \
--url http://127.0.0.1:17493/mcp \
--header "X-Voicebox-Client-Id: claude-code"
```
**任意 HTTP MCP 客户端**（Cursor、Windsurf、VS Code 等）：
```json
{
"mcpServers": {
"voicebox": {
"url": "http://127.0.0.1:17493/mcp",
"headers": { "X-Voicebox-Client-Id": "cursor" }
}
}
}
```
**Stdio 回退方案**，适用于不支持 HTTP MCP 的客户端 — 指向应用内捆绑的 `voicebox-mcp` 二进制文件：
```json
{
"mcpServers": {
"voicebox": {
"command": "/Applications/Voicebox.app/Contents/MacOS/voicebox-mcp",
"env": { "VOICEBOX_CLIENT_ID": "claude-desktop" }
}
}
}
```
内置四个工具：`voicebox.speak`、`voicebox.transcribe`、`voicebox.list_captures`、`voicebox.list_profiles`。按客户端的语音绑定在 **Voicebox → Settings → MCP** 中管理。有关工具签名、解析优先级、speaking-pill 合约和安全说明，请参阅[完整 MCP 指南](docs/content/docs/overview/mcp-server.mdx)。
```ts
// In any MCP-aware agent:
await voicebox.speak({
text: "Tests passing. Ready to merge.",
profile: "Morgan", // optional — falls back to the per-client binding
personality: true, // optional — rewrites text through the profile's personality LLM first
});
```
**使用场景：** 智能体开发循环（语音输入、语音输出）、游戏对话、播客制作、无障碍工具、语音助手、内容自动化。
完整 API 文档请参阅 `http://127.0.0.1:17493/docs`。
---
## 技术栈
| 层级 | 技术 |
| ------------- | ------------------------------------------------------------------------------- |
| 桌面应用 | Tauri (Rust) |
| 前端 | React, TypeScript, Tailwind CSS |
| 状态管理 | Zustand, React Query |
| 后端 | FastAPI (Python) |
| TTS 引擎 | Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro |
| STT | Whisper / Whisper Turbo (PyTorch or MLX) |
| 本地 LLM | Qwen3 (0.6B / 1.7B / 4B), 与 TTS / STT 共享运行时 |
| MCP 服务器 | FastMCP 挂载于 `/mcp`（Streamable HTTP）+ 捆绑的 stdio shim 二进制文件 |
| 原生 Shim | Rust（Tauri 内部），用于全局快捷键、粘贴注入、焦点内省 |
| 特效 | Pedalboard (Spotify) |
| 推理 | MLX (Apple Silicon) / PyTorch (CUDA/ROCm/XPU/CPU) |
| 数据库 | SQLite |
| 音频 | WaveSurfer.js, librosa |
---
## 路线图
| 功能 | 描述 |
| ---------------------------------- | ------------------------------------------------------------------------ |
| **Windows / Linux 自动粘贴** | 听写粘贴功能对齐 — Windows 上使用 `SendInput`，Linux 上使用 `uinput` / AT-SPI |
| **STT 引擎扩展** | Parakeet v3 和 Qwen3-ASR 加入 Whisper — 支持 50+ 种语言，非英语质量更佳 |
| **流水线路由** | 可配置的 source → transform → sink 链路，支持 webhook + MCP sink 及预设编辑器 |
| **流式转录** | WebSocket `/transcribe/stream`，说话时实时输出部分转录结果 |
| **端到端语音 LLM** | Moshi、GLM-4-Voice、Qwen2.5 Omni — 真正的语音到语音，中间无需文本 |
| **语音设计（Voice Design）** | 根据文本描述创建新语音 |
| **长格式录制** | 双流录制器（麦克风 + 系统音频），附带摘要 LLM 转换 |
| **平台 Sink** | Apple Notes、Obsidian 及其他可选集成 |
| **插件架构** | 通过自定义模型、转换和 sink 进行扩展 |
| **移动端伴侣应用** | 用手机控制 Voicebox |
有关**完整工程状态、开放 issue 分类与优先级工作队列**，请参阅 [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) — 这是一份动态文档，跟踪已交付内容、进行中的工作、正在评估的候选 TTS 引擎，以及我们接受或暂缓特定集成的原因。
---
## 开发
详细的环境搭建与贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
### 快速开始
```bash
git clone https://github.com/jamiepine/voicebox.git
cd voicebox
just setup # creates Python venv, installs all deps
just dev # starts backend + desktop app
```
安装 [just](https://github.com/casey/just): `brew install just` 或 `cargo install just`。运行 `just --list` 查看所有命令。
**前置条件：** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), 以及 macOS 上的 [Xcode](https://developer.apple.com/xcode/)。
仓库在根目录提供预配置的 `.mcp.json` — 在此代码库中运行 Claude Code 时，一旦开发版应用启动，即可自动加载 Voicebox MCP 工具。
### 本地构建
```bash
just build # Build CPU server binary + Tauri app
just build-local # (Windows) Build CPU + CUDA server binaries + Tauri app
```
### 添加新语音模型
多引擎架构使添加新 TTS 引擎变得简单。[分步指南](docs/content/docs/developer/tts-engines.mdx) 涵盖完整流程：依赖调研、后端协议实现、前端接入和 PyInstaller 打包。
该指南针对 AI 编程智能体进行了优化。[agent skill](.agents/skills/add-tts-engine/SKILL.md) 只需接收模型名称即可自主完成整个集成 — 你只需在本地测试构建。
### 项目结构
```
voicebox/
├── app/ # Shared React frontend
├── tauri/ # Desktop app (Tauri + Rust)
├── web/ # Web deployment
├── backend/ # Python FastAPI server
├── landing/ # Marketing website
└── scripts/ # Build & release scripts
```
---
## 贡献
欢迎贡献！指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 提交 PR
## 安全
发现安全漏洞？请负责任地报告。详情请参阅 [SECURITY.md](SECURITY.md)。
---
## 许可证
MIT 许可证 — 详情请参阅 [LICENSE](LICENSE)。
---
voicebox.sh