内容
# 语音盒
本地优先的 AI 语音工作室 — 克隆声音，合成语音，在任意应用程序中进行语音输入，并将 MCP 代理连接到自定义语音。所有推理都在您的硬件上运行；除非您明确配置远程访问，否则音频永远不会离开您的机器。
> **版本 0.5.0** · Bun monorepo · TypeScript-first stack · Tauri desktop · React UI
---
## 目录
- [概述](#概述)
- [架构](#架构)
- [功能亮点](#功能亮点)
- [项目结构](#项目结构)
- [安装](#安装)
- [配置](#配置)
- [开发](#开发)
- [测试](#测试)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [常见问题](#常见问题)
- [许可证](#许可证)
---
## 概述
语音盒在一个应用程序中结合了语音**输入**（Whisper STT + 全局语音输入热键）和语音**输出**（七个 TTS 引擎，支持克隆、特效和分段）。一个捆绑的本地 LLM 优化了转录稿并驱动了每个配置文件的人物。
| 界面 | 技术栈 | 目的 |
|---------|-------|---------|
| 桌面应用程序 | Tauri 2 + Rust | 原生热键、音频 I/O、侧车管理 |
| 共享 UI | React 18 + TypeScript | 桌面和网页共享的界面 |
| API 层 | TypeScript-first 服务接口 | 语音和会话集成 |
| 网页部署 | Vite + 可选的持久化缓存 | 自托管的浏览器可访问构建 |
| 营销 | Next.js | [voicebox.sh](https://voicebox.sh) 公共网站 |
---
## 架构
### 系统上下文
```mermaid
flowchart TB
subgraph Client["客户端层"]
Desktop["Tauri 桌面"]
Browser["网页浏览器"]
end
subgraph UI["共享 React UI（app/）"]
Routes["TanStack 路由器"]
Stores["Zustand 状态管理"]
Platform["平台适配器"]
end
subgraph Backend["API 服务层"]
API["REST + SSE 路由"]
SVC["服务 + 任务队列"]
ENG["TTS / STT 引擎"]
MCP["MCP 服务器 /mcp"]
DB[(SQLite)]
end
subgraph Persist["可选持久化"]
Cache[(持久化缓存)]
end
Desktop --> UI
Browser --> UI
UI -->|HTTP / SSE| API
Desktop -->|侧车| Backend
API --> SVC --> ENG
SVC --> DB
MCP --> SVC
Browser -.->|网页部署| Cache
```
### 请求流程 — 语音生成
```mermaid
sequenceDiagram
participant U as 用户
participant R as React UI
participant F as API 服务
participant Q as 任务队列
participant E as TTS 引擎
U->>R: 输入文本 + 选择配置文件
R->>F: POST /generations
F->>Q: 排队合成任务
Q->>E: 运行引擎推理
E-->>Q: 音频块 + 进度
Q-->>F: SSE 进度事件
F-->>R: 流式传输状态
R-->>U: 播放 + 下载
```
### 平台抽象
原生功能（文件系统、更新器、音频捕获）在 `app/src/platform/types.ts` 中定义。每个部署目标都提供了自己的实现：
- **桌面** — `tauri/src/platform/`（完全原生访问）
- **网页** — `web/src/platform/`（浏览器安全存根）
---
## 功能亮点
- **七个 TTS 引擎** — Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox 多语言/涡轮, HumeAI TADA, Kokoro
- **语音克隆** — 从短参考样本进行零镜头克隆
- **23 种语言** — 主要语言家族的多语言合成
- **全局语音输入** — 系统范围的热键，粘贴到聚焦字段
- **音频特效** — 音高、混响、延迟、合唱、压缩、过滤器
- **MCP 集成** — 用于代理驱动的语音工作流的 HTTP MCP 服务器
- **本地 LLM 优化** — 用于转录清理的捆绑 Qwen3 模型
- **可选持久化缓存** — 用于网页托管的会话和部署持久化
---
## 项目结构
```
voicebox/
├── app/ # 共享 React 应用程序
├── tauri/ # 桌面壳（Vite + Rust）
├── web/ # 浏览器部署包装器
│ └── src/server/ # Node 持久化启动
├── landing/ # 营销网站
├── src/ # 根 TypeScript 实用程序和运行时模块
│ └── redis/ # 持久化连接管理器 + 缓存 API
├── scripts/ # 构建和发布自动化
├── biome.json # Lint + 格式化（JS/TS）
└── justfile # 主要开发编排
```
---
## 安装
### 先决条件
| 工具 | 版本 | 注意 |
|------|---------|-------|
| [Bun](https://bun.sh) | ≥ 1.0 | JavaScript 包管理器 |
| Rust | 稳定版 | Tauri 桌面构建所需 |
| FFmpeg | 任意近期版本 | 音频处理 |
### 快速设置（推荐）
```bash
# 克隆并进入仓库
git clone https://github.com/jamiepine/voicebox.git
cd voicebox
# 安装 JavaScript/TypeScript 依赖项
just setup
# 启动开发模式
just dev
```
### 本地开发
```bash
bun run dev:web
# 网页应用可在 http://127.0.0.1:5173 访问
```
### 桌面发布
从 [GitHub Releases](https://github.com/jamiepine/voicebox/releases) 下载适用于 macOS、Windows 和 Linux 的预构建二进制文件。
---
## 配置
### 应用程序
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `VOICEBOX_HOST` | `127.0.0.1` | API 绑定地址 |
| `VOICEBOX_PORT` | `17493` | API 端口 |
| `VOICEBOX_CORS_ORIGINS` | — | 额外的 CORS 来源（逗号分隔） |
| `LOG_LEVEL` | `info` | 应用程序日志级别 |
### 持久化缓存（可选 — 网页部署）
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `VOICEBOX_REDIS_ENABLED` | `false` | 启用 Redis 持久化 |
| `VOICEBOX_REDIS_URL` | — | 完整的连接 URL |
| `VOICEBOX_REDIS_HOST` | `127.0.0.1` | URL 未设置时的主机 |
| `VOICEBOX_REDIS_PORT` | `6379` | 端口 |
| `VOICEBOX_REDIS_KEY_PREFIX` | `voicebox:` | 键命名空间 |
参见 [.env.redis.example](.env.redis.example) 获取完整列表。
当持久化缓存禁用或无法访问时，连接管理器会透明地回退到内存存储。
### MCP 客户端
将您的 MCP 客户端指向 `http://127.0.0.1:17493/mcp`。示例配置在 `.mcp.json` 中。
---
## 开发
### 常用命令
```bash
just dev # 网页开发模式
bun run dev:web # 仅网页 UI
bun run typecheck # 跨所有工作区的 TypeScript
bun run check # Biome lint + 格式化
bun run test # TypeScript 持久化单元测试
just check # 仓库检查
```
### 添加 TTS 引擎
遵循 `.agents/skills/add-tts-engine/SKILL.md` 中的代理技能，并镜像 TypeScript 应用程序模块中的现有模式。
---
## 测试
| 层 | 命令 | 框架 |
|-------|---------|-----------|
| TypeScript | `bun run test` | Vitest（TypeScript 持久化测试） |
| TypeScript | `bun run typecheck` | tsc 严格模式 |
| Rust | `cargo test`（在 `tauri/src-tauri` 中） | cargo test |
| CI | `bun run ci` | typecheck + Biome + Vitest + 网页构建 |
```bash
# 在打开 PR 之前在本地运行所有测试
bun run ci
```
---
## 故障排除
### 服务无法启动
1. 确认已安装依赖项（`just setup`）。
2. 检查端口 17493 是否空闲：`curl http://127.0.0.1:17493/health`。
3. 查看日志中的启动失败和缺少的运行时依赖项。
### Tauri 开发编译失败（缺少侧车）
运行 `bun run setup:dev` 以创建占位符侧车二进制文件，然后重启 `bun run dev`。
### 网页构建类型错误
从仓库根目录运行 `bun run typecheck`。所有工作区（`app`、`web`、`tauri`、`landing`）和根目录 `src/` 都包含在内。
### 持久化连接错误
设置 `VOICEBOX_REDIS_ENABLED=false` 以使用内存回退，或验证缓存后端是否可达：
```bash
docker run --rm -p 6379:6379 redis:7-alpine
export VOICEBOX_REDIS_ENABLED=true
bun run bootstrap:persistence
```
### 模型下载失败
确保有足够的磁盘空间和网络访问权限，以便进行 HuggingFace 下载。设置 `HF_TOKEN` 以获取受限模型。
扩展指南：[docs.voicebox.sh](https://docs.voicebox.sh) → 故障排除。
---
## 贡献
1. 分叉仓库并从 `main` 创建功能分支。
2. 如果这是您的第一个贡献，请运行 `just setup`。
3. 遵循现有的约定 — TypeScript 使用 Biome。
4. 确保 `bun run ci` 在打开 PR 之前通过。
5. 在更改用户可见的行为时更新文档。
参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 获取编码标准和审查期望。
---
## 常见问题
**我的语音数据会被发送到云端吗？**
否。默认情况下，所有模型和音频都保留在您的机器上。远程模式需要显式配置。
**支持哪些 GPU？**
NVIDIA CUDA、Apple MLX（macOS）、AMD ROCm（Windows/Linux 叠加）和 CPU 回退。
**我可以将 Voicebox 用作 API 服务器吗？**
是的。应用程序在运行时公开 REST API 接口。除 localhost 外，请仅在受信任的网络上绑定。
**为什么需要可选的持久化缓存？**
缓存层是可选的，主要有利于需要共享会话或缓存状态的自托管网页部署。
**它与 ElevenLabs 或 Wispr Flow 有何不同？**
Voicebox 是开源的，本地运行，并在一个栈中涵盖了语音合成和语音输入，支持 MCP 代理集成。
---
## 许可证
参见 [`LICENSE`](LICENSE) 获取详细信息。
---
**链接：** [网站](https://voicebox.sh) · [文档](https://docs.voicebox.sh) · [发布](https://github.com/jamiepine/voicebox/releases) · [安全策略](SECURITY.md)
