wehub/jamiepine--voicebox

Fork 0

Files

T

wehub-resource-sync 380aa18090

CI / frontend-quality (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 09:54:59 +00:00

25 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 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
macOS (Intel)	Download DMG
Windows	Download MSI
Docker	`docker compose up`

查看全部二进制文件 →

Linux — 预编译二进制文件尚未提供。请参阅 voicebox.sh/linux-install 了解从源码构建的说明。

遇到问题？ 请参阅故障排除指南，了解常见的安装、生成、模型下载和 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。

Captures（采集）

每次听写、应用内录制和上传的音频文件都会进入 Captures 标签页 — 原始音频与转写文本配对保存，始终保留。

重放、重新转写、润色 — 可用任意 Whisper 尺寸重新运行 STT，或将原始转写文本通过本地 LLM 以不同标志重跑（填充词清理、自我纠正移除、技术术语保留）
内联编辑 — 调整转写文本，失焦时保存
作为语音配置文件播放 — 一键将任意采集转为克隆语音朗读
提升为语音样本 — 将采集的音频 + 转写文本用作任意语音配置文件的参考样本
本地采集存储 — 原始音频与转写文本保存在 Voicebox 数据目录，设置中提供文件夹快捷方式

智能体语音输出

每个智能体都有声音。一次工具调用，任意支持 MCP 的智能体即可用你克隆的语音对你说话 — 任务完成、提问、通知等。听写时显示的同一条 pill 在智能体说话时也会出现，因此你始终能看到机器正在输出什么。

// 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 集成到你自己的应用与智能体中。

# 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 等）：

{
  "mcpServers": {
    "voicebox": {
      "url": "http://127.0.0.1:17493/mcp",
      "headers": { "X-Voicebox-Client-Id": "cursor" }
    }
  }
}

Stdio 回退方案，适用于不支持 HTTP MCP 的客户端 — 指向应用内捆绑的 voicebox-mcp 二进制文件：

{
  "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 指南。

// 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 — 这是一份动态文档，跟踪已交付内容、进行中的工作、正在评估的候选 TTS 引擎，以及我们接受或暂缓特定集成的原因。

开发

详细的环境搭建与贡献指南请参阅 CONTRIBUTING.md。

快速开始

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: brew install just 或 cargo install just。运行 just --list 查看所有命令。

前置条件： Bun, Rust, Python 3.11+, Tauri Prerequisites, 以及 macOS 上的 Xcode。

仓库在根目录提供预配置的 .mcp.json — 在此代码库中运行 Claude Code 时，一旦开发版应用启动，即可自动加载 Voicebox MCP 工具。

本地构建

just build          # Build CPU server binary + Tauri app
just build-local    # (Windows) Build CPU + CUDA server binaries + Tauri app

添加新语音模型

多引擎架构使添加新 TTS 引擎变得简单。分步指南涵盖完整流程：依赖调研、后端协议实现、前端接入和 PyInstaller 打包。

该指南针对 AI 编程智能体进行了优化。agent skill 只需接收模型名称即可自主完成整个集成 — 你只需在本地测试构建。

项目结构

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。

Fork 仓库
创建功能分支
进行更改
提交 PR

安全

发现安全漏洞？请负责任地报告。详情请参阅 SECURITY.md。

许可证

MIT 许可证 — 详情请参阅 LICENSE。

voicebox.sh

25 KiB Raw Permalink Blame History Unescape Escape