wehub/jamiepine--voicebox
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
CI / frontend-quality (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 09:54:59 +00:00
parent 39792e43f8
commit 380aa18090
1 changed files with 191 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+191 -187
View File
@@ -1,3 +1,9 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/jamiepine/voicebox) · [上游 README](https://github.com/jamiepine/voicebox/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
<p align="center">
<img src=".github/assets/icon-dark.webp" alt="Voicebox" width="120" height="120" />
</p>
@@ -5,9 +11,9 @@
<h1 align="center">Voicebox</h1>
<p align="center">
<strong>The open-source AI voice studio.</strong><br/>
Clone any voice. Generate speech. Dictate into any app. Talk to agents in voices you own.<br/>
The full voice I/O stack, running locally on your machine.
<strong>开源 AI 语音工作室。</strong><br/>
克隆任意声音。生成语音。向任意应用听写。用你拥有的声音与智能体对话。<br/>
完整的语音输入/输出（voice I/O）技术栈，在本地机器上运行。
</p>
<p align="center">
@@ -50,7 +56,7 @@
</p>
<p align="center">
<em>Click the image above to watch the demo video on <a href="https://voicebox.sh">voicebox.sh</a></em>
<em>点击上方图片，在 <a href="https://voicebox.sh">voicebox.sh</a> 观看演示视频</em>
</p>
<br/>
@@ -65,30 +71,30 @@
<br/>
## What is Voicebox?
## 什么是 Voicebox？
Voicebox is a **local-first AI voice studio** — a free and open-source alternative to **ElevenLabs** and **WisprFlow** in one app. Clone voices from a few seconds of audio, generate speech in 23 languages across 7 TTS engines, dictate into any text field with a global hotkey, and give any MCP-aware AI agent a voice of your choosing.
Voicebox 是一款**本地优先（local-first）的 AI 语音工作室**——在一个应用中免费开源地替代 **ElevenLabs** 和 **WisprFlow**。只需几秒音频即可克隆声音，通过 7 款 TTS 引擎以 23 种语言生成语音，用全局快捷键向任意文本框听写，并为任意支持 MCP 的 AI 智能体指定你想要的声音。
The two cloud incumbents sit on opposite halves of the voice I/O loop — ElevenLabs on output, WisprFlow on input. Voicebox does both, bridges them with a bundled local LLM for refinement and per-profile personas, and runs the whole thing on your machine.
两家云端 incumbent 分别占据语音 I/O 循环的两端——ElevenLabs 负责输出，WisprFlow 负责输入。Voicebox 两者兼顾，通过内置本地 LLM 进行润色和按配置 persona 定制，并将整套流程运行在你的机器上。
- **Complete privacy** — models, voice data, and captures never leave your machine
- **7 TTS engines** — Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox Multilingual, Chatterbox Turbo, HumeAI TADA, and Kokoro
- **Voice cloning and preset voices** — zero-shot cloning from a reference sample, or 50+ curated preset voices via Kokoro and Qwen CustomVoice
- **23 languages** — from English to Arabic, Japanese, Hindi, Swahili, and more
- **Post-processing effects** — pitch shift, reverb, delay, chorus, compression, and filters
- **Expressive speech** — paralinguistic tags like `[laugh]`, `[sigh]`, `[gasp]` via Chatterbox Turbo; natural-language delivery control via Qwen CustomVoice
- **Unlimited length** — auto-chunking with crossfade for scripts, articles, and chapters
- **Stories editor** — multi-track timeline for conversations, podcasts, and narratives
- **Voice input** — global dictation hotkey with push-to-talk and toggle modes, accessibility-verified auto-paste on macOS, in-app mic on every text field, Whisper-based STT
- **Agent voice output** — one tool call (`voicebox.speak`) and any MCP-aware agent (Claude Code, Cursor, Cline) speaks to you in a voice you've cloned
- **Voice personalities** — attach a free-form persona to any voice profile, then Compose, Rewrite, or Respond via a bundled local LLM — agents can invoke the same modes over MCP
- **API-first** — REST API plus a built-in MCP server for integrating voice I/O into your own apps and agents
- **Native performance** — built with Tauri (Rust), not Electron
- **Runs everywhere** — macOS (MLX/Metal), Windows (CUDA), Linux, AMD ROCm, Intel Arc, Docker
- **完全隐私** — 模型、语音数据和录音绝不会离开你的机器
- **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
---
## Download
## 下载
| Platform | Download |
| --------------------- | ------------------------------------------------------ |
@@ -97,138 +103,136 @@ The two cloud incumbents sit on opposite halves of the voice I/O loop — Eleven
| Windows | [Download MSI](https://voicebox.sh/download/windows) |
| Docker | `docker compose up` |
> **[View all binaries →](https://github.com/jamiepine/voicebox/releases/latest)**
> **[查看全部二进制文件 →](https://github.com/jamiepine/voicebox/releases/latest)**
> **Linux** — Pre-built binaries are not yet available. See [voicebox.sh/linux-install](https://voicebox.sh/linux-install) for build-from-source instructions.
> **Linux** — 预编译二进制文件尚未提供。请参阅 [voicebox.sh/linux-install](https://voicebox.sh/linux-install) 了解从源码构建的说明。
> **Having trouble?** See the [Troubleshooting Guide](docs/content/docs/overview/troubleshooting.mdx) for common install, generation, model-download, and GPU issues.
> **遇到问题？** 请参阅[故障排除指南](docs/content/docs/overview/troubleshooting.mdx)，了解常见的安装、生成、模型下载和 GPU 问题。
---
## Features
## 功能
### Multi-Engine Voice Cloning
### 多引擎声音克隆
Seven TTS engines with different strengths, switchable per-generation:
七款 TTS 引擎各有优势，可按每次生成切换：
| Engine | Languages | Strengths |
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Qwen3-TTS** (0.6B / 1.7B) | 10 | High-quality multilingual cloning, delivery instructions ("speak slowly", "whisper") |
| **Qwen CustomVoice** | 10 | 9 curated preset voices with natural-language delivery control — no reference audio required |
| **LuxTTS** | English | Lightweight (~1GB VRAM), 48kHz output, 150x realtime on CPU |
| **Chatterbox Multilingual** | 23 | Broadest language coverage — Arabic, Danish, Finnish, Greek, Hebrew, Hindi, Malay, Norwegian, Polish, Swahili, Swedish, Turkish and more |
| **Chatterbox Turbo** | English | Fast 350M model with paralinguistic emotion/sound tags |
| **TADA** (1B / 3B) | 10 | HumeAI speech-language model — 700s+ coherent audio, text-acoustic dual alignment |
| **Kokoro** | 8 | 50 curated preset voices, tiny 82M model, fast CPU inference |
| **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 推理速度快 |
### Emotions & Paralinguistic Tags
### 情感与副语言标签
Only **Chatterbox Turbo** interprets paralinguistic tags like `[laugh]` and
`[sigh]`. Qwen3-TTS, LuxTTS, Chatterbox Multilingual, and HumeAI TADA read them
literally as text.
仅 **Chatterbox Turbo** 会解析 `[laugh]` 和
`[sigh]` 等副语言标签。Qwen3-TTS、LuxTTS、Chatterbox Multilingual 和 HumeAI TADA 会将其字面朗读为文本。
With **Chatterbox Turbo** selected, type `/` in the text input to open the tag
inserter and add expressive tags inline with speech:
选择 **Chatterbox Turbo** 后，在文本输入框中输入 `/` 即可打开标签插入器，在语音中内联添加表现力标签：
`[laugh]` `[chuckle]` `[gasp]` `[cough]` `[sigh]` `[groan]` `[sniff]` `[shush]` `[clear throat]`
### Post-Processing Effects
### 后处理效果
8 audio effects powered by Spotify's `pedalboard` library. Apply after generation, preview in real time, build reusable presets.
8 种音频效果，由 Spotify 的 `pedalboard` 库驱动。生成后应用，实时预览，可构建可复用预设。
| Effect | Description |
| ---------------- | --------------------------------------------- |
| Pitch Shift | Up or down by up to 12 semitones |
| Reverb | Configurable room size, damping, wet/dry mix |
| Delay | Echo with adjustable time, feedback, and mix |
| Chorus / Flanger | Modulated delay for metallic or lush textures |
| Compressor | Dynamic range compression |
| Gain | Volume adjustment (-40 to +40 dB) |
| High-Pass Filter | Remove low frequencies |
| Low-Pass Filter | Remove high frequencies |
| Pitch Shift | 上下最多 12 个半音 |
| Reverb | 可配置房间大小、阻尼、湿/干混合 |
| Delay | 可调时间、反馈和混合比的回声 |
| Chorus / Flanger | 调制延迟，营造金属感或丰厚质感 |
| Compressor | 动态范围压缩 |
| Gain | 音量调节（-40 至 +40 dB） |
| High-Pass Filter | 去除低频 |
| Low-Pass Filter | 去除高频 |
Ships with 4 built-in presets (Robotic, Radio, Echo Chamber, Deep Voice) and supports custom presets. Effects can be assigned per-profile as defaults.
内置 4 种预设（Robotic、Radio、Echo Chamber、Deep Voice），并支持自定义预设。效果可按配置文件（profile）分别设为默认项。
### Unlimited Generation Length
### 无限生成长度
Text is automatically split at sentence boundaries and each chunk is generated independently, then crossfaded together. Works with all engines.
文本会在句子边界自动切分，每个分块独立生成，再通过交叉淡入淡出拼接在一起。适用于所有引擎。
- Configurable auto-chunking limit (100–5,000 chars)
- Crossfade slider (0–200ms) for smooth transitions
- Max text length: 50,000 characters
- Smart splitting respects abbreviations, CJK punctuation, and `[tags]`
- 可配置自动分块上限（100–5,000 字符）
- 交叉淡入淡出滑块（0–200ms），实现平滑过渡
- 最大文本长度：50,000 字符
- 智能切分会识别缩写、CJK 标点以及 `[tags]`
### Generation Versions
### 生成版本
Every generation supports multiple versions with provenance tracking:
每次生成均支持多版本，并带有来源（provenance）追踪：
- **Original** — clean TTS output, always preserved
- **Effects versions** — apply different effects chains from any source version
- **Takes** — regenerate with a new seed for variation
- **Source tracking** — each version records its lineage
- **Favorites** — star generations for quick access
- **Original（原始）** — 干净的 TTS 输出，始终保留
- **Effects versions（效果版本）** — 从任意源版本应用不同的效果链
- **Takes（重录）** — 使用新种子重新生成以产生变化
- **Source tracking（来源追踪）** — 每个版本都会记录其谱系
- **Favorites（收藏）** — 为生成结果加星标，便于快速访问
### Async Generation Queue
### 异步生成队列
Generation is non-blocking. Submit and immediately start typing the next one.
生成过程不阻塞界面。提交后即可立即开始输入下一条。
- Serial execution queue prevents GPU contention
- Real-time SSE status streaming
- Failed generations can be retried
- Stale generations from crashes auto-recover on startup
- 串行执行队列，避免 GPU 争用
- 实时 SSE 状态流式推送
- 失败的生成可重试
- 因崩溃产生的陈旧生成任务，在启动时会自动恢复
### Voice Profile Management
### 语音配置文件管理
- Create profiles from audio files or record directly in-app
- Import/export profiles to share or back up
- Multi-sample support for higher quality cloning
- Per-profile default effects chains
- Organize with descriptions and language tags
- 从音频文件创建配置文件，或在应用内直接录制
- 导入/导出配置文件，便于分享或备份
- 多样本支持，提升克隆质量
- 每个配置文件可设置默认效果链
- 通过描述和语言标签进行组织管理
### Stories Editor
### Stories 编辑器
Multi-voice timeline editor for conversations, podcasts, and narratives.
面向对话、播客和叙事内容的多声部时间线编辑器。
- Multi-track composition with drag-and-drop
- Inline audio trimming and splitting
- Auto-playback with synchronized playhead
- Version pinning per track clip
- 多轨编排，支持拖放
- 内联音频裁剪与分割
- 自动播放，播放头同步
- 每个轨道片段可固定版本
### Global Dictation & Voice Input
### 全局听写与语音输入
The other half of the voice I/O loop. Hold a hotkey anywhere on your system, speak, release — on macOS the transcript pastes straight into the focused text field. Or hit the mic on any Voicebox text input and dictate directly into the app.
语音 I/O 循环的另一半。在系统任意位置按住快捷键，说话，松手 — 在 macOS 上，转写文本会直接粘贴到当前聚焦的文本框。或在任意 Voicebox 文本输入框点击麦克风，直接在应用内听写。
- **Configurable chord bindings** — hold-to-speak and tap-to-toggle chords, each rebindable in the in-app chord picker. Holding push-to-talk and tapping `Space` mid-hold upgrades into a toggle session without a gap in audio
- **Target-aware paste (macOS)** — accessibility-verified injection into the focused text field, with atomic clipboard save/restore so your clipboard isn't clobbered
- **First-run permissions UX** — in-app gates walk you through the macOS Accessibility and Input Monitoring grants with deep-links to System Settings
- **In-app mic button** on every Voicebox text field — generation form, profile descriptions, story titles, anywhere you'd type
- **LLM refinement** — optional cleanup of ums, stutters, and false starts before paste
- **On-screen pill** — floating overlay surfacing `recording`, `transcribing`, `refining`, and `speaking` states. Same pill agents use when they speak to you, so there's one mental model for both directions of the loop
- **可配置组合键绑定** — 按住说话与点按切换两种组合键，均可在应用内组合键选择器中重新绑定。按住 push-to-talk 期间点按 `Space`，可在不中断音频的情况下升级为切换会话
- **目标感知粘贴（macOS）** — 经无障碍（accessibility）校验后注入到聚焦文本框，并原子化保存/恢复剪贴板，避免覆盖你的剪贴板内容
- **首次运行权限引导** — 应用内门禁会引导你完成 macOS 无障碍与输入监控授权，并提供直达系统设置的深链接
- **应用内麦克风按钮** — 每个 Voicebox 文本输入框均有：生成表单、配置文件描述、故事标题等所有可输入处
- **LLM 润色** — 粘贴前可选清理“嗯”、口吃和说错开头
- **屏幕悬浮条（pill）** — 浮动叠加层展示 `recording`、`transcribing`、`refining` 与 `speaking` 状态。与智能体对你说话时使用的同一条 pill 一致，因此语音循环双向共用同一心智模型
### Speech-to-Text
### 语音转文字（Speech-to-Text）
Voicebox runs OpenAI Whisper for transcription — the same model that backs dictation, the Captures tab, and the `/transcribe` API. Running on MLX (Apple Silicon) or PyTorch (CUDA / ROCm / DirectML / CPU) depending on your platform.
Voicebox 使用 OpenAI Whisper 进行转写 — 与听写、Captures 标签页以及 `/transcribe` API 共用同一模型。根据平台在 MLX（Apple Silicon）或 PyTorch（CUDA / ROCm / DirectML / CPU）上运行。
| Size | Notes |
| ----------------------------- | -------------------------------------------------- |
| Base / Small / Medium / Large | Standard Whisper quality ladder |
| Turbo | ~8x faster than Whisper Large, minimal quality loss |
| Base / Small / Medium / Large | 标准 Whisper 质量阶梯 |
| Turbo | 比 Whisper Large 快约 8 倍，质量损失极小 |
More engines (Parakeet v3, Qwen3-ASR) are planned — see [Roadmap](#roadmap).
更多引擎（Parakeet v3、Qwen3-ASR）已在规划中 — 见 [Roadmap](#roadmap)。
### Captures
### Captures（采集）
Every dictation, in-app recording, and uploaded audio file lands in the Captures tab — original audio paired with transcript, always preserved.
每次听写、应用内录制和上传的音频文件都会进入 Captures 标签页 — 原始音频与转写文本配对保存，始终保留。
- **Replay, re-transcribe, refine** — rerun STT with any Whisper size, or re-run the raw transcript through the local LLM with different flags (filler cleanup, self-correction removal, technical-term preservation)
- **Edit inline** — tweak the transcript and save on blur
- **Play as voice profile** — turn any capture into speech with a cloned voice, one click
- **Promote to voice sample** — use a capture's audio + transcript as a reference sample on any voice profile
- **Local capture storage** — original audio and transcript stay in your Voicebox data directory, with a folder shortcut in Settings
- **重放、重新转写、润色** — 可用任意 Whisper 尺寸重新运行 STT，或将原始转写文本通过本地 LLM 以不同标志重跑（填充词清理、自我纠正移除、技术术语保留）
- **内联编辑** — 调整转写文本，失焦时保存
- **作为语音配置文件播放** — 一键将任意采集转为克隆语音朗读
- **提升为语音样本** — 将采集的音频 + 转写文本用作任意语音配置文件的参考样本
- **本地采集存储** — 原始音频与转写文本保存在 Voicebox 数据目录，设置中提供文件夹快捷方式
### Agent Voice Output
### 智能体语音输出
Every agent gets a voice. One tool call and any MCP-aware agent can speak to you in a voice you've cloned — task completions, questions, notifications. The same pill that surfaces during dictation surfaces during agent speech, so you always see what's coming out of your machine.
每个智能体都有声音。一次工具调用，任意支持 MCP 的智能体即可用你克隆的语音对你说话 — 任务完成、提问、通知等。听写时显示的同一条 pill 在智能体说话时也会出现，因此你始终能看到机器正在输出什么。
```ts
// In any MCP-aware agent:
@@ -238,49 +242,49 @@ await voicebox.speak({
});
```
Also exposed as `POST /speak` for anything that doesn't speak MCP — ACP, A2A, shell scripts, custom harnesses.
同时也以 `POST /speak` 形式暴露，供非 MCP 语音场景使用 — ACP、A2A、shell 脚本、自定义 harness 等。
- **Bidirectional pill** — `recording`, `transcribing`, `refining`, and `speaking` are all states of the same OS-level overlay, so dictation and agent speech share one surface
- **Per-agent voice binding** — in **Settings → MCP**, pin Claude Code to Morgan and Cursor to Scarlett so you can tell which agent is talking without looking. Each client's `last_seen_at` timestamp confirms the install actually took
- **Always visible** — no silent background TTS; every agent-initiated speak surfaces the pill with the voice profile name for the full duration
- **HTTP + stdio transports** — install as a URL in Claude Code / Cursor / Windsurf / VS Code MCP, or point stdio-only clients at the bundled `voicebox-mcp` binary
- **双向 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
### 语音个性（Voice Personalities）
Attach a free-form personality to any voice profile — who this voice is, how they speak, what they care about. Two actions appear on the generate box when a personality is set, powered by a bundled Qwen3 LLM running entirely locally.
可为任意语音配置文件附加自由格式的个性描述 — 这个声音是谁、如何说话、关心什么。设置个性后，生成框会出现两个操作，由捆绑的 Qwen3 LLM 完全在本地驱动。
- **Compose** — a shuffle button that drops a fresh in-character line into the textarea; edit and speak, or click again for a different take
- **Speak in character** — a toggle that routes your input text through the personality LLM to be rewritten in their voice before TTS
- **Compose（创作）** — 洗牌按钮，向文本区域放入一条符合角色设定的新台词；可编辑后朗读，或再次点击换一版
- **Speak in character（角色化朗读）** — 开关将你的输入文本先经个性 LLM 改写成该角色口吻，再进行 TTS
Agents can reach the same rewrite path over MCP by passing `personality: true` to `voicebox.speak`, turning the tool into a text-in → personality-LLM → TTS pipeline. The same LLM backs dictation's refinement step — one LLM in the app, one model cache, one GPU-memory footprint.
智能体也可通过 MCP 走同一路径：向 `voicebox.speak` 传入 `personality: true`，将工具变为 文本输入 → 个性 LLM → TTS 流水线。同一 LLM 也支撑听写润色步骤 — 应用内一个 LLM、一个模型缓存、一份 GPU 显存占用。
**Local LLM options:** Qwen3 0.6B / 1.7B / 4B, sharing the TTS runtime (MLX on Apple Silicon, PyTorch elsewhere).
**本地 LLM 选项：** Qwen3 0.6B / 1.7B / 4B，与 TTS 运行时共享（Apple Silicon 用 MLX，其他平台用 PyTorch）。
Use cases: agent dev loops (dictate a question, hear the answer in a cloned voice), interactive characters for games and narrative tools, speech assistance for people who can't speak in their original voice.
用例：智能体开发循环（听写提问、用克隆语音听答案）、游戏与叙事工具的交互角色、为无法以原声说话的人提供语音辅助。
### Model Management
### 模型管理
- Per-model unload to free GPU memory without deleting downloads
- Custom models directory via `VOICEBOX_MODELS_DIR`
- Model folder migration with progress tracking
- Download cancel/clear UI
- 按模型卸载以释放 GPU 显存，无需删除已下载文件
- 通过 `VOICEBOX_MODELS_DIR` 自定义模型目录
- 模型文件夹迁移，带进度追踪
- 下载取消/清理 UI
### GPU Support
### GPU 支持
| Platform | Backend | Notes |
| ------------------------ | -------------- | ---------------------------------------------- |
| macOS (Apple Silicon) | MLX (Metal) | 4-5x faster via Neural Engine |
| Windows / Linux (NVIDIA) | PyTorch (CUDA) | Auto-downloads CUDA binary from within the app |
| Linux (AMD) | PyTorch (ROCm) | Auto-configures HSA_OVERRIDE_GFX_VERSION |
| Windows (any GPU) | DirectML | Universal Windows GPU support |
| Intel Arc | IPEX/XPU | Intel discrete GPU acceleration |
| Any | CPU | Works everywhere, just slower |
| 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 exposes a REST API for integrating voice I/O into your own apps and agents.
Voicebox 提供 REST API，便于将语音 I/O 集成到你自己的应用与智能体中。
```bash
# Generate speech
@@ -303,13 +307,13 @@ curl -X POST http://127.0.0.1:17493/transcribe \
curl http://127.0.0.1:17493/profiles
```
`POST /speak` accepts `profile` as a name (case-insensitive) or id, and resolves via the same precedence as the MCP tool: explicit arg → per-client binding → `capture_settings.default_playback_voice_id`.
`POST /speak` 接受 `profile` 作为名称（不区分大小写）或 id，并通过与 MCP 工具相同的优先级进行解析：显式参数 → 按客户端绑定 → `capture_settings.default_playback_voice_id`。
### MCP server
### MCP 服务器
Voicebox ships a built-in **Model Context Protocol** server so any MCP-aware agent (Claude Code, Cursor, Windsurf, Cline, VS Code MCP extensions) can speak, transcribe, and browse captures and profiles.
Voicebox 内置 **Model Context Protocol（MCP）** 服务器，任何支持 MCP 的智能体（Claude Code、Cursor、Windsurf、Cline、VS Code MCP 扩展）都可以进行语音合成、转录，以及浏览录制内容和配置文件。
**Claude Code one-liner:**
**Claude Code 一行配置：**
```
claude mcp add voicebox \
@@ -318,7 +322,7 @@ claude mcp add voicebox \
--header "X-Voicebox-Client-Id: claude-code"
```
**Any HTTP MCP client** (Cursor, Windsurf, VS Code, etc.):
**任意 HTTP MCP 客户端**（Cursor、Windsurf、VS Code 等）：
```json
{
@@ -331,7 +335,7 @@ claude mcp add voicebox \
}
```
**Stdio fallback** for clients that don't speak HTTP MCP — point at the bundled `voicebox-mcp` binary inside the app:
**Stdio 回退方案**，适用于不支持 HTTP MCP 的客户端 — 指向应用内捆绑的 `voicebox-mcp` 二进制文件：
```json
{
@@ -344,7 +348,7 @@ claude mcp add voicebox \
}
```
Four tools ship: `voicebox.speak`, `voicebox.transcribe`, `voicebox.list_captures`, `voicebox.list_profiles`. Per-client voice bindings are managed in **Voicebox → Settings → MCP**. See the [full MCP guide](docs/content/docs/overview/mcp-server.mdx) for tool signatures, resolution precedence, the speaking-pill contract, and security notes.
内置四个工具：`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:
@@ -355,56 +359,56 @@ await voicebox.speak({
});
```
**Use cases:** agent dev loops (voice in, voice out), game dialogue, podcast production, accessibility tools, voice assistants, content automation.
**使用场景：** 智能体开发循环（语音输入、语音输出）、游戏对话、播客制作、无障碍工具、语音助手、内容自动化。
Full API documentation available at `http://127.0.0.1:17493/docs`.
完整 API 文档请参阅 `http://127.0.0.1:17493/docs`。
---
## Tech Stack
## 技术栈
| Layer | Technology |
| 层级 | 技术 |
| ------------- | ------------------------------------------------------------------------------- |
| Desktop App | Tauri (Rust) |
| Frontend | React, TypeScript, Tailwind CSS |
| State | Zustand, React Query |
| Backend | FastAPI (Python) |
| TTS Engines | Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro |
| 桌面应用 | 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) |
| Local LLM | Qwen3 (0.6B / 1.7B / 4B), shared runtime with TTS / STT |
| MCP Server | FastMCP mounted at `/mcp` (Streamable HTTP) + bundled stdio shim binary |
| Native Shim | Rust (inside Tauri) for global hotkey, paste injection, focus introspection |
| Effects | Pedalboard (Spotify) |
| Inference | MLX (Apple Silicon) / PyTorch (CUDA/ROCm/XPU/CPU) |
| Database | SQLite |
| Audio | WaveSurfer.js, librosa |
| 本地 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 |
---
## Roadmap
## 路线图
| Feature | Description |
| 功能 | 描述 |
| ---------------------------------- | ------------------------------------------------------------------------ |
| **Windows / Linux auto-paste** | Dictation paste parity — `SendInput` on Windows, `uinput` / AT-SPI on Linux |
| **STT engine expansion** | Parakeet v3 and Qwen3-ASR joining Whisper — 50+ languages, better non-English quality |
| **Pipeline routing** | Configurable source → transform → sink chains with webhook + MCP sinks and a preset editor |
| **Streaming transcription** | WebSocket `/transcribe/stream` for partial transcripts as you speak |
| **End-to-end speech LLMs** | Moshi, GLM-4-Voice, Qwen2.5 Omni — real voice-to-voice, no text between |
| **Voice Design** | Create new voices from text descriptions |
| **Long-form capture** | Dual-stream recorder (mic + system audio) with summary LLM transform |
| **Platform sinks** | Apple Notes, Obsidian, and other opt-in integrations |
| **Plugin architecture** | Extend with custom models, transforms, and sinks |
| **Mobile companion** | Control Voicebox from your phone |
| **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 |
For the **full engineering status, open-issue triage, and prioritized work queue**, see [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) — a living document that tracks what's shipped, what's in-flight, candidate TTS engines under evaluation, and why we've accepted or backlogged specific integrations.
有关**完整工程状态、开放 issue 分类与优先级工作队列**，请参阅 [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) — 这是一份动态文档，跟踪已交付内容、进行中的工作、正在评估的候选 TTS 引擎，以及我们接受或暂缓特定集成的原因。
---
## Development
## 开发
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed setup and contribution guidelines.
详细的环境搭建与贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
### Quick Start
### 快速开始
```bash
git clone https://github.com/jamiepine/voicebox.git
@@ -414,26 +418,26 @@ just setup # creates Python venv, installs all deps
just dev # starts backend + desktop app
```
Install [just](https://github.com/casey/just): `brew install just` or `cargo install just`. Run `just --list` to see all commands.
安装 [just](https://github.com/casey/just): `brew install just` 或 `cargo install just`。运行 `just --list` 查看所有命令。
**Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS.
**前置条件：** [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/)。
The repo ships a pre-wired `.mcp.json` at the root — running Claude Code inside this checkout picks up the Voicebox MCP tools automatically once the dev app is running.
仓库在根目录提供预配置的 `.mcp.json` — 在此代码库中运行 Claude Code 时，一旦开发版应用启动，即可自动加载 Voicebox MCP 工具。
### Building Locally
### 本地构建
```bash
just build # Build CPU server binary + Tauri app
just build-local # (Windows) Build CPU + CUDA server binaries + Tauri app
```
### Adding New Voice Models
### 添加新语音模型
The multi-engine architecture makes adding new TTS engines straightforward. A [step-by-step guide](docs/content/docs/developer/tts-engines.mdx) covers the full process: dependency research, backend protocol implementation, frontend wiring, and PyInstaller bundling.
多引擎架构使添加新 TTS 引擎变得简单。[分步指南](docs/content/docs/developer/tts-engines.mdx) 涵盖完整流程：依赖调研、后端协议实现、前端接入和 PyInstaller 打包。
The guide is optimized for AI coding agents. An [agent skill](.agents/skills/add-tts-engine/SKILL.md) can pick up a model name and handle the entire integration autonomously — you just test the build locally.
该指南针对 AI 编程智能体进行了优化。[agent skill](.agents/skills/add-tts-engine/SKILL.md) 只需接收模型名称即可自主完成整个集成 — 你只需在本地测试构建。
### Project Structure
### 项目结构
```
voicebox/
@@ -447,24 +451,24 @@ voicebox/
---
## Contributing
## 贡献
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
欢迎贡献！指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Submit a PR
1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 提交 PR
## Security
## 安全
Found a security vulnerability? Please report it responsibly. See [SECURITY.md](SECURITY.md) for details.
发现安全漏洞？请负责任地报告。详情请参阅 [SECURITY.md](SECURITY.md)。
---
## License
## 许可证
MIT License — see [LICENSE](LICENSE) for details.
MIT 许可证 — 详情请参阅 [LICENSE](LICENSE)。
---