Voicebox 版本演进全解:从 0.1.0 单引擎语音克隆到 0.5.0 语音 I/O 中枢

本文以 Voicebox 仓库根目录的 CHANGELOG.md 为主体,完整梳理该项目从 2026-01-27 首个公开版 0.1.0 到 0.5.0 "Capture release" 的全部版本脉络:多引擎 TTS 架构、PyInstaller 打包可靠性、i18n 本地化、离线模式修复三部曲,以及 0.5.0 的听写(Capture)、人格(Personality)、MCP 服务器与 Refinement 四条主线。读完本文,你可以掌握 Voicebox 每个里程碑版本解决了什么问题,并能沿文中给出的源码路径(如 MCP 工具注册、人格服务)直接深入实现细节做二次开发或故障排查。

一、版本时间线总览

Voicebox 的发布节奏大约经历了四个阶段:

版本区间	阶段主题	一句话概括
0.1.0 – 0.1.13	桌面语音克隆 App	基于 Qwen3-TTS 的 Tauri v2 桌面应用,平台支持逐步铺开(macOS → Windows → MLX 加速)
0.2.0 – 0.2.3	多引擎重构	四引擎并立、23 语言、无限长文本自动分块、异步生成队列、Docker,以及 PyInstaller 冻结构建的一连串修复
0.3.0 – 0.4.5	架构与可靠性	后端模块化拆分、文档站迁移 Fumadocs、引擎扩到七个、GPU 支持 Intel Arc/Blackwell、i18n、离线模式崩溃的三次热修
0.5.0	Capture release	全局热键听写 + 自动粘贴、MCP 服务器让任意 Agent 开口说话、本地 LLM 人格化改写、Whisper 后的 LLM 精炼管线

CHANGELOG 文件头部注明它由发布工作流自动编译,手工修改会被覆盖;草稿更新与定稿分别由 draft-release-notes 与 release-bump 两个 agent skill 驱动(见 CHANGELOG.md 顶部注释)。前端在构建时会解析这份文件,渲染进应用的 Changelog 设置页——对应实现位于 changelog 插件 与 parseChangelog 工具。

二、0.1.x:单引擎语音克隆的桌面化之路

2.1 0.1.0 首发的能力基线

0.1.0(2026-01-27)定义了 Voicebox 最初的技术形态:

• 语音克隆:基于 Qwen3-TTS,模型从 HuggingFace 自动下载,提供 1.7B 与 0.6B 两种规格;带 voice prompt 缓存以支持快速重生成;支持英文与中文。
• 语音档案管理:可从音频文件或直接录音创建档案,单档案支持多份样本提升克隆质量,支持档案导入/导出,样本经 Whisper 自动转录。
• 语音生成:选定档案的文本转语音,提供 seed 控制保证可复现,长文本支持到 5,000 字符。
• 生成历史:带元数据的完整历史、按文本搜索、内联播放与下载。
• 部署形态:本地模式(捆绑后端)与远程模式(局域网 GPU 服务器)两种,一键服务器配置。
• 技术栈:Tauri v2(Rust)+ React + TypeScript + Tailwind CSS + FastAPI + Qwen3-TTS + Whisper + SQLite——官方明确"不是 Electron,且无需用户安装 Python"。

2.2 0.1.1 – 0.1.13 的平台铺轨

0.1.x 系列后续版本围绕平台与下载体验快速迭代,几条主线值得记住:

• 音频采集三件套(0.1.2):音频格式转换工具、macOS/Windows 系统音频采集增强、macOS 音频输入权限项,并补了采集测试。
• 跨平台采集(0.1.1):macOS 原生采集、Windows WASAPI 实现(改进线程安全);Linux 构建当时因 runner 磁盘空间受限临时移除——这个坑在 0.4.2 的 Linux 条目里被再次提及。
• Stories 编辑器(0.1.6):首个时间线式多语音叙事编辑器,支持轨道编排、片段内联编辑,奠定了后来 0.5.0 "timeline editor" 升级的基础。
• 下载超时修复(0.1.8):Windows 上下载报 "Failed to fetch" 的问题,通过将下载端点改为"立即返回 + 后台继续下载"解决;同时修掉了硬编码的 ~/.cache/huggingface/hub 路径,统一走 hf_constants.HF_HUB_CACHE 实现跨平台缓存解析。
• MLX 后端(0.1.10):Apple Silicon 上单次生成从约 20s 降到 2–3s。这是 Voicebox 最早的"按平台动态选后端"设计——运行时检测平台,macOS 选 MLX、其他平台选 PyTorch。这一设计在 后端注册表 中依然可见:get_tts_backend_for_engine() 按 get_backend_type() 在 MLXTTSBackend 与 PyTorchTTSBackend 之间分叉。
• 模型下载 UX(0.1.12):带精确百分比与速度信息的实时进度、更新通知不再依赖手动检查。

三、0.2.x:多引擎重构与冻结构建的可靠性战役

3.1 0.2.1:四引擎并立的地基版本

0.2.1(2026-03-15)是架构上的分水岭,核心是把 Voicebox 从"Qwen3-TTS 单引擎 App"重构成四引擎多后端体系。原始 CHANGELOG 中的引擎规格表如下(完整保留,数值与当前源码中的 ModelConfig 注册一致):

引擎	语言数	体积	关键特性
Qwen3-TTS 1.7B	10	约 3.5 GB	最高质量,支持 delivery instructions
Qwen3-TTS 0.6B	10	约 1.2 GB	更轻更快的变体
LuxTTS	英语	约 300 MB	CPU 友好、48 kHz 输出、约 150 倍实时速度
Chatterbox Multilingual	23	约 3.2 GB	语言覆盖最广,零样本克隆
Chatterbox Turbo	英语	约 1.5 GB	350M 参数、低延迟、副语言标签

这版的关键能力:

• 线程安全的按引擎后端注册表:引擎可在单次生成之间从下拉框切换,无需重启。对应实现即 backends 包入口:_tts_backends 字典 + _tts_backends_lock 双检锁,每个引擎独立实例化(get_tts_backend_for_engine)。注意 0.5.0 之后该注册表已扩到七个 TTS 引擎加一个 LLM 引擎(见 TTS_ENGINES 定义)。
• 无限长生成与自动分块:长文本按句子边界切块、逐块生成、交叉淡化拼回,与引擎无关。参数化配置:分块上限滑块 100–5,000 字符(默认 800)、交叉淡化 0–200ms(默认 50ms)、文本长度上限提到 50,000 字符;切分逻辑尊重缩写、CJK 标点与 [tags]。分块实现位于 chunked_tts 工具。
• 异步生成队列:生成完全非阻塞,串行队列防止 GPU 争用,SSE 实时推送状态。队列的状态机(queued/running/cancelled)由 task_queue 服务 管理,0.4.1 又在此之上加了取消能力。
• 生成版本(Generation Versions):每条生成支持多版本与来源追踪——原始版、特效版、take、来源跟踪、Stories 版本固定与收藏。
• 后期音效管线:基于 Spotify 的 pedalboard 库,提供 Pitch Shift、Reverb、Delay、Chorus/Flanger、Compressor、Gain、High-Pass/Low-Pass Filter,4 个内置预设 + 自定义预设 + 按档案默认特效 + 实时试听(后端实现见 effects 服务 与 effects 工具函数)。
• 副语言标签补全:选中 Chatterbox Turbo 时,在文本框输入 / 打开 9 个表情标签补全:[laugh] [chuckle] [gasp] [cough] [sigh] [groan] [sniff] [shush] [clear throat]。0.4.1 在文档中进一步澄清:这些标签只有 Chatterbox Turbo 支持,其他引擎会按字面文本朗读。
• 平台:Windows 完整支持(含 CUDA GPU 检测)、Linux(AMD ROCm、NVIDIA GBM 修复、WebKitGTK 麦克风)、应用内下载并热换 CUDA 后端、PyTorch 后端支持 Intel Arc(XPU)与 DirectML、Docker + Web 部署(三阶段构建、非 root 运行、健康检查)、Whisper Turbo(openai/whisper-large-v3-turbo)转录选项。
• 安全与可靠性:CORS 加固、网络访问开关、离线崩溃修复、原子化音频写入、文件系统健康端点。

3.2 0.2.2 – 0.2.3:让"开发机能跑"变成"生产包能跑"

0.2.3 是典型的打包修复版,主题可概括为"it works in dev but not in prod":

• 模型下载链路修复:Chatterbox、Chatterbox Turbo、LuxTTS 在捆绑包中都能下载、加载、生成。根因之一是 huggingface_hub 会根据日志级别静默关闭 tqdm 进度条,导致字节级进度追踪失效,最终通过强制启用内部计数器解决。
• Python 3.12.0 的 code.replace() 缺陷:macOS 构建用的 3.12.0 踩中 PyInstaller 重写 code object 时损坏字节的 CPython 已知缺陷,导致 scipy/torch 导入时 NameError: name 'obj' is not defined;升级到 3.12.13 解决。
• PyInstaller 收集清单:一系列 --collect-all——inflect(typeguard 的 @typechecked 在导入时调 inspect.getsource())、perth(Chatterbox 运行时水印模型)、piper_phonemize(LuxTTS 的 espeak-ng 数据,并设置 ESPEAK_DATA_PATH)、linacodec(Vocos codec)、zipvoice(LuxTTS 声音克隆);为 requests、transformers 等复制 metadata 以修复 importlib.metadata 查询;multiprocessing.freeze_support() 修 resource_tracker 子进程崩溃;--noconsole 只在 Windows 生效(macOS/Linux 需要 stdout/stderr 供 Tauri sidecar 捕获日志)。

这些细节与 0.4.1 的冻结二进制修复一脉相承,共同构成 Voicebox 生产包可靠性的两大基石;仓库中对应的 PyInstaller 钩子源码仍在 pyi_hooks 目录(如 hook-transformers.masking_utils.py)与 PyInstaller 运行时钩子。

四、0.3.0:后端模块化重构与文档站迁移

0.3.0(2026-03-17)是一次纯工程结构升级:

• 后端重构:3,100 行单体 main.py 拆成 backend/routes/ 下 13 个领域路由,main.py 降到约 10 行;CRUD 与业务逻辑移入 backend/services/,平台检测进 backend/utils/,单文件 database.py 拆成 database 包(models/session/migrations/seed 四个模块);TTS 后端的共享逻辑去重到 backends/base.py;新增 STYLE_GUIDE.md 与 ruff 配置。当前仓库的 routes 目录(audio、captures、generations、profiles、stories 等 20 个路由文件)即此次重构的直接产物。
• 设置页改造:拆成 General / Generation / GPU / Logs / Changelog / About 路由子页,新增服务器日志实时查看器、解析 CHANGELOG.md 的应用内 Changelog 页、About 页;抽出可复用的 SettingRow 组件(对应 SettingRow 组件)。
• 音频播放器修复:播放中卡死、重启竞态、重渲染 key 稳定性、可访问性改进。
• 文档站迁移 Mintlify → Fumadocs(Next.js):重写介绍页、生成 OpenAPI 规格并自动生成 API 参考页。当前仓库 docs 目录 即 Fumadocs 工程,API 参考页(如 profiles 接口)与开发者指南(如 tts-engines)都保留至今。
• Bug 修复一批:样本上传导致服务器崩溃(音频解码改线程池)、生成列表不刷新(refetchQueries 缓存失效)、错误 toast 显示 [object Object]、Whisper 模型选择扩展到 /transcribe 端点、CUDA 构建 cu121 → cu126 以支持 RTX 50 系、SSE 端点处理客户端断开、Docker pip hash 不匹配、50 MB 上传上限等。

五、0.4.0:七引擎阵容与 GPU 矩阵扩张

0.4.0(2026-04-16)是 0.5.0 之前最大的功能版本,三个新引擎把阵容扩到七个:

• HumeAI TADA(tada-1b 英语、tada-3b-ml 多语言):用轻量 DAC shim 替换 descript-audio-codec 削减依赖,音频解码切到 soundfile 绕开 torchcodec 打包问题,受限 Llama tokenizer 查询改走非 gated 镜像(实现见 hume_backend 与 dac_shim)。
• Kokoro 82M:新引擎同时引入"预设声音"与"克隆档案"的档案类型系统——此前所有引擎都是克隆模型,预设型引擎的加入第一次打破了"每个档案都可用于每个引擎"的假设。由此产生本版最重要的 UX 决策:
  • 置灰而非过滤:所有档案永远可见,不兼容的渲染为变暗并附提示;
  • 选中即自动切换引擎:点击置灰档案会把它选上并切到兼容引擎;
  • Qwen CustomVoice 恢复 instruct 开关:浮动生成框只在 CustomVoice 被选中时显示 delivery-instructions 输入框,因为这是唯一真正为指令式风格控制训练过的引擎。
• Qwen CustomVoice:基于 Qwen3-TTS 的预设引擎,并在全链路强制预设/档案与引擎的兼容性。

5.1 GPU 与平台

• Intel Arc(XPU):所有 PyTorch 后端一等支持,XPU 检测进入 GPU 状态面板与设置流程,正确报告设备名与显存。
• Blackwell / RTX 50 系:CUDA 后端 cu126 → cu128,构建经 TORCH_CUDA_ARCH_LIST 加入 sm_120+PTX 前向兼容。
• GPU 兼容性诊断:新增 check_cuda_compatibility()(当前实现位于 backends/base.py),把当前设备计算能力与捆绑 PyTorch 的架构列表比对;健康端点暴露 gpu_compatibility_warning 字段,启动时不匹配打 WARN 日志,GPU 状态标签显示 [UNSUPPORTED - see logs],不再无声地 "no kernel image"。
• CUDA 后端拆包:拆成两个独立版本管理的归档——小的服务器二进制与约 4 GB PyTorch/CUDA DLL 的大 libs 归档;升级 Voicebox 不再重复下载 libs。用 asyncio.Lock 包住 download_cuda_binary() 防止自动更新与手动下载竞写同一临时文件;package_cuda.py 适配 PyInstaller 6.18 onedir 布局(见 package_cuda 脚本)。

5.2 关键 Bug 修复(0.4.0)

• numpy 2.x torch.from_numpy 崩溃:torch 按 numpy 1.x ABI 编译,配对 numpy 2.x 时每个 TTS 请求都报 RuntimeError: Numpy is not available;requirements 固定 numpy<2.0,并加 PyInstaller 运行时钩子用 ctypes.memmove 兜底,后加固为未知 dtype 直接抛错而非静默按 float32 重解释。
• Windows 后台服务器:/watchdog/disable 请求可能输给进程退出,新增 .keep-running 哨兵文件作为同步兜底,启动时清理陈旧哨兵。
• macOS 11 启动崩溃:ScreenCaptureKit 弱链接使应用在 macOS 12.3 以下可启动;系统音频采集用 sw_vers 真实版本检查做门控。
• macOS Intel:放宽 torch>=2.7.0 → torch>=2.2.0,因为 PyTorch 在 2.2.2 后不再提供 x86_64 预编译轮子。
• Stories 拆分竞态:后端加 with_for_update() 行锁,前端加 isPending 守卫。
• 历史状态陈旧:GET /history/{id} 原来硬编码 status="completed",现改为返回真实行的 status/error/engine/model_size/is_favorited。
• 安全加固:voice prompt 缓存改用 torch.load(weights_only=True);字符串路径守卫换 Path.is_relative_to()。
• Docker:CHANGELOG.md 打进 web 构建(应用内 changelog 页在 Docker 部署中可用);compose 设置 NUMBA_CACHE_DIR。

六、0.4.1 – 0.4.5:生产包修复与离线模式三部曲

6.1 0.4.1:让新引擎在生产二进制里真正加载

0.4.0 引入的三个新引擎在冻结的 PyInstaller 二进制上撞了 Python 生态的几根钉子,0.4.1 一次性扫清:

• Kokoro:transformers 的 _can_set_attn_implementation 正则扫描要读 .py 源码,此前 FileNotFoundError: kokoro/modules.py 直接杀死加载——现在用 --collect-all kokoro 把 .py 与 .pyc 一起打包;
• Chatterbox Multilingual:捆绑 spacy_pkuseg/dicts/default.pkl 与原生 .so,修复中文分词器首载崩溃;
• scipy.stats._distn_infrastructure:运行时钩子源码修补结尾的 del obj——冻结导入器下前置列表推导求值为空,del obj 会抛 NameError;改成 globals().pop('obj', None),解锁所有依赖 librosa 的 TTS 引擎(对应钩子 hook-scipy.stats._distn_infrastructure.py);
• transformers.masking_utils:同型运行时钩子强制 _is_torch_greater_or_equal_than_2_6 = False,走旧版 sdpa_mask_older_torch 路径,因为 2.6+ 路径用 torch._dynamo 真实图变换(对应 hook-transformers.masking_utils.py);
• torch._dynamo 空实现桩:在 transformers 导入前替换真实模块,阻止 torch._numpy._ufuncs 导入崩溃;
• .spec 路径改为仓库相对路径,生成的 spec 可跨机器/CI 移植。

其他能力:生成取消(/generate/{id}/cancel 端点 + 历史行 Stop 按钮,串行队列按 ID 追踪 queued/running/cancelled 状态)、旧 data/ 路径前缀解析修复、迁移对话框空缓存不再挂起、Linux 系统音频采集(pactl get-default-sink + pactl list short sources,环境变量 PULSE_SOURCE 路由)、前端 CI 首道质量门(bun run typecheck + bun run build:web)。

6.2 0.4.2:全应用本地化

0.4.2 把整个 App 做了四语言本地化:英语、简体中文(zh-CN)、繁体中文(zh-TW)、日语(ja),每个语言 559 个翻译键、覆盖每个 tab/弹窗/对话框/toast,无部分覆盖或英文回退。当前仓库 i18n 目录 中可见 9 个语言目录(en/es/fr/it/ja/ko/pt-BR/zh-CN/zh-TW,说明 0.5.0 期间又继续扩了语种)。实现要点:

• i18next 底座 + 应用内语言切换器,切换时以显式 key-bump 重渲染 React 根节点(懒加载组件否则持有陈旧字符串);
• 相对日期经 date-fns locale 对象本地化(3 days ago → 3 天前 / 3 日前),而不是 Intl.RelativeTimeFormat;
• 开发构建的版本后缀按语言显示:v0.4.2 (dev) / (开发版) / (開發版) / (開発版)。

同版可靠性修复值得单独记:HF_HUB_OFFLINE 守卫所有推理路径;Chatterbox 参考样本不再被拒收而是重采样适配;MLX Qwen 0.6B 指向正确的 mlx-community 仓库;macOS 系统音频在应用失焦后不再被 WKWebView 拆掉;MLX 后端 miniaudio 依赖固定版本。另有两个已知事实:官网新增 /download 页(当前 landing 源码 即其产物);Linux 构建再次暂停——CI 在 ubuntu-22.04 的 tauri-action 打包步骤挂起 25 分钟以上,矩阵条目重新禁用。

6.3 0.4.3 – 0.4.5:"offline mode is enabled" 崩溃三部曲

这三版构成一次教科书级的热修链,值得完整保留:

1. 0.4.3(2026-04-20):两个可靠性重点——macOS DMG 公证与 Kokoro 日语。Tauri 打包器只公证 DMG 内的 .app 而不管 DMG 外壳,Gatekeeper 在 macOS 15 Sequoia 拒绝它;发布工作流改为对每个 DMG 提交 notarytool、staple 票据、spctl 校验,解锁 brew install voicebox。Kokoro 日语新装崩溃的根因是 misaki[ja] 经 fugashi 需要 MeCab 词典,而原安装的 unidic 包不带数据、指望一个 just setup 不会执行的 526 MB 运行时下载(且 PyInstaller 冻结后也留不住);换成自带词典的 unidic-lite(约 50 MB),并在 build_binary.py 中收集 unidic_lite/dicdir/。
2. 0.4.4(2026-04-21):回滚 0.4.3 引入的推理路径守卫。0.4.3 曾给所有推理主体(generate、transcribe、create_voice_clone_prompt)包上进程级 HF_HUB_OFFLINE 翻转来防网络中断时的 HuggingFace 查询挂起,但该标志同时挡住了合法元数据调用(如 revision 解析的 HfApi().model_info),在线用户反而全面失败。回滚后推理恢复进程默认 HF 状态,保留加载期守卫。已知代价:无网生成时可能出现约 30s 的 HuggingFace 元数据超时暂停,预告 0.4.5 提供正解。
3. 0.4.5(2026-04-22):第二次热修,直接消掉问题类别。transformers 4.57.x 在 AutoTokenizer.from_pretrained 内部(经 _patch_mistral_regex)对每个非本地仓库加载加了无条件 huggingface_hub.model_info() 调用,与 0.4.2 的加载期 HF_HUB_OFFLINE 守卫叠加后,缓存命中的在线用户一加载就硬崩。修复方式:包一层 _patch_mistral_regex 的异常处理——HF 元数据检查抛任何异常都捕获并原样返回 tokenizer,行为与非 Mistral 仓库的成功路径对齐;包装器在 backend.backends 导入时安装,因此覆盖 Qwen Base、Qwen CustomVoice、TADA 等所有 transformers 系引擎。同时移除加载期 force_offline_if_cached 守卫(有了包装器它们零收益且有复发风险)。离线用户也不再等 30s 超时。该补丁的现行实现即 hf_offline_patch 模块,并由 backends 包入口 在任何后端导入 transformers 之前先行安装——注释里明确写着"防止 HF_HUB_OFFLINE=1 或网络故障时 tokenizer 加载抛错"。

七、0.5.0(Capture release):从克隆工作室到语音 I/O 中枢

0.5.0(2026-04-22)是 Voicebox 定位的转折点:按住机器上任意处的热键、说话、松手,转写文本落进聚焦的输入框;反过来,任何支持 MCP 的 Agent(Claude Code、Cursor 等)都能用你克隆的声音通过屏幕上的"语音胶囊"说话,中间夹一个本地 LLM 让转写变干净、让人格重塑 Agent 的发言。四大主线逐条拆解,并对照当前源码。

7.1 听写:全局热键采集与自动粘贴

CHANGELOG 记载的交互设计:

• 全局热键:按住可自定义的键和(默认 macOS 为右 Cmd + 右 Option,Windows 为右 Ctrl + 右 Shift),说话,松手。屏幕浮动胶囊走 recording → transcribing → refining → done 全流程,带实时计时;产出干净文本。默认键和常量可从 capture_chords 模块 直接读到:macOS 为 ["MetaRight", "AltGr"],非 macOS 为 ["ControlRight", "ShiftRight"]。
• PTT 与 toggle 双模式,各配一个键和:默认 toggle 键和在 PTT 键和上加一个 Space;按住 PTT 时点一下 Space 可在录音无断点的情况下把"按住"升级为免提会话(macOS 为 ["MetaRight", "AltGr", "Space"],见 default_toggle_to_talk_chord)。
• 自动粘贴到启动时的焦点应用:转写完成后合成一次粘贴,落到"你开始按热键时"的焦点文本框——不是说话期间焦点漂移到的地方;跨 Dvorak/AZERTY 布局可用;剪贴板先保存、后恢复。
• 键和选择器 UI:Settings → Captures 里按住你想用的键即可自定义,左右修饰键有徽章区分左/右变体。
• 默认键和的避撞设计:macOS 默认避开左手 Cmd+Option 键和(不与系统快捷键冲突);Windows 默认避开德语/法语/西语布局中 Ctrl+Alt 即 AltGr 的组合键冲突。
• 辅助功能权限的作用域化:macOS 未授予 Accessibility 权限时,听写照常运行、转写照常进 Captures tab,只是禁用合成粘贴;权限提示内联在 auto-paste 开关旁,而非全局横幅。

7.2 人格:会说话的语音档案

语音档案现在携带可选的 personality 自由文本描述(最长 2000 字符)。设置后,生成按钮旁出现两个新控件,都由同一个本地 Qwen3 LLM 驱动:

• Compose(洗牌按钮):往文本框扔一句新的角色内台词,再点有变化,可编辑后再发音;
• Speak in character(魔棒开关):你的输入先过人格 LLM 再进 TTS——保留全部观点,但用角色的口吻表达。

关键约束是**"应用里只有一个本地 LLM,不是两个"**:人格模型与 Refinement 复用同一实例。这一点在 personality 服务 的模块注释里写得非常清楚,而且实现里有两处值得注意的温度设计:

• compose_as_profile 用 temperature=0.9、max_tokens=256,系统提示只含角色设定 + 任务描述,用户轮固定为 "Speak."——高温保证连续点击的多样性;
• rewrite_as_profile 用 temperature=0.3、max_tokens=1024,且输入先过 collapse_repetitive_artifacts 清洗再送 LLM——低温保语义保真(对应 compose/rewrite 双入口)。

系统提示刻意保持短小,注释解释了原因:"小模型(0.6B)在长系统提示下会退化"。

API 面(CHANGELOG 原文保留):POST /generate、POST /speak 与 MCP voicebox.speak 工具接受 personality: bool;POST /profiles/{id}/compose 驱动洗牌按钮;MCP 客户端绑定携带 default_personality: bool,在未显式传 personality 时生效。

7.3 MCP 服务器:让任意 Agent 拥有声音

Voicebox 在 http://127.0.0.1:17493/mcp 内置了一个 Model Context Protocol 服务器,默认端口 17493 与 app.py 中的 CORS 白名单 一致。当前实现位于 mcp_server 包:FastMCP 实例经 mcp.http_app(path="/", transport="http") 以 Streamable HTTP 挂到 FastAPI 的 /mcp 路径,ClientIdMiddleware 装在外层,保证工具执行前 ContextVar 里已有 X-Voicebox-Client-Id。

四个工具(dotted 命名,在 Agent 日志里读起来自然,见 tools 注册):

工具	能力	源码佐证
voicebox.speak	用任意档案发音;可选 personality: true 先过人格 LLM;返回 generation id 供轮询 /generate/{id}/status;音频落到 Captures/History tab	voicebox_speak
voicebox.transcribe	Whisper 转写 base64 音频或绝对本地路径;路径模式仅限 loopback 调用方——防止绑定在 0.0.0.0 的 Voicebox 变成未鉴权的任意本地文件读取原语;200 MB 上限(MAX_TRANSCRIBE_BYTES)	voicebox_transcribe
voicebox.list_captures	最近的语音捕获及转写,limit 1–200	同文件
voicebox.list_profiles	可用档案(克隆 + 预设),返回 has_personality 字段	同文件

传输与绑定机制:

• Streamable HTTP 为主传输:Cursor / Windsurf / VS Code / Claude Code 开箱支持,配置一个带 URL 和 X-Voicebox-Client-Id 请求头的 mcpServers 块即可;
• stdio shim:不支持 HTTP MCP 的客户端用应用包内的 voicebox-mcp 二进制(Tauri sidecar)。它本质是一个 stdio ↔ Streamable-HTTP 的 JSON-RPC 代理:把每行 stdin 的 JSON-RPC 转发到 http://127.0.0.1:<port>/mcp/,响应流回 stdout;支持 VOICEBOX_PORT/VOICEBOX_HOST/VOICEBOX_CLIENT_ID 环境变量;诊断信息走 stderr;退出码 0/1/2 分别对应正常 EOF/传输错误/后端无响应(完整实现见 mcp_shim)。Settings 页渲染的安装片段会预填正确绝对路径。
• 按客户端语音绑定:把 Claude Code 绑到 Morgan、Cursor 绑到 Scarlett——speak 未显式传 profile 时,X-Voicebox-Client-Id 解析到绑定档案,在 Settings → MCP 管理。
• 档案解析优先级(CHANGELOG 四步,与 resolve_profile 逐行对应):
  1. 显式 profile 参数(名称或 id,大小写不敏感);
  2. 该客户端的 MCPClientBinding.profile_id 绑定;
  3. capture_settings.default_playback_voice_id 全局默认;
  4. 以上皆无则报错并指向 Settings 页面。
• 语音胶囊(speaking pill):Agent 发起的发言呈现与听写相同的屏幕胶囊,speaking 状态显示档案名与计时器。_speak_response 里发布 speak-start 事件、run_generation 完成钩子发结束事件(见 事件发布处)——注释的原话是"无声后台 TTS 是信任风险,胶囊永远显示你机器上正在出来的东西"。
• POST /speak REST 封装:与 MCP 同一代码路径、同一语音解析,供 shell 脚本、ACP、A2A、GitHub Actions 等非 MCP 原生场景使用(路由见 speak.py)。

Claude Code 一行安装(CHANGELOG 原文保留):

claude mcp add voicebox --transport http --url http://127.0.0.1:17493/mcp --header "X-Voicebox-Client-Id: claude-code"

7.4 Refinement:Whisper 之后的 LLM 精炼

干净的转写光靠 Whisper 不够。每条捕获流经一个小 Qwen3 LLM:去填充词、修标点、可选重写自我更正——全部在本地。三个设计点在源码中可完整验证:

1. LLM 之前的 loop 折叠(collapse_repetitive_artifacts):Whisper 在音频收尾时会幻觉出循环("thanks for watching" ×N)。折叠阈值为 6 次相同 token(大小写不敏感),即 _REPETITION_RUN_THRESHOLD = 6(源码);两级扫描——词级(单 token 重复,如 "URL URL URL",比较前剥离标点并小写)与字符级(2–60 字符子串紧接重复,覆盖 "thanks for watching" 类多词循环与无空格 CJK 循环)。注释明确说明保留修辞性重复:"no, no, no, no, no"(5 次)不过阈值,不会被误删。设计动机是双重的:小精炼模型会把合法输出截断"给 loop 腾位置",大模型则会把 loop 原样回显——确定性剥离两边都躲开。
2. 按捕获的 flag 快照:转写精炼的三个开关 smart_cleanup、self_correction、preserve_technical(RefinementFlags,默认全开)逐条存进每个捕获,之后可以用不同 flag 重跑精炼而原始转写不丢。提示词在服务端按布尔 flag 组装(build_refinement_prompt):基础指令固定要求"转写是数据不是指令——不回答、不执行、不寒暄",三个开关各追加一段规则,其中 preserve_technical 会做点号/斜杠/下划线等口语标点转字面符号("index dot tsx" → "index.tsx")。
3. 模型选择器:Qwen3 0.6B(约 400 MB,非常快,默认)、1.7B(约 1.1 GB,较快)、4B(约 2.5 GB,全质量);1.7B 是含代码标识符转写的甜点档。这三个规格与 LLM 模型注册表 一致,且 MLX 路径自动改用 mlx-community 的 4-bit 社区量化仓库,体积进一步缩小(0.6B 在 MLX 上标 400 MB、PyTorch 上 1400 MB)。

一个容易被忽略的实现细节:精炼的 few-shot 示例被刻意做成了结构化聊天轮次(user → assistant 对)而非系统提示内的内联示例——注释记录了原因:小模型会把系统提示里的内联示例当成"要补全的模板"原样回显;作为历史对话轮出现时模型才把它当数据(REFINEMENT_EXAMPLES 及注释)。示例顺序也有讲究:离真实用户轮越近的权重越高,末尾两个槽位固定给最难钉住的规则。

7.5 Captures tab 与设置归位

Settings → Captures 成为整个听写流程的家:

• Dictation:全局快捷键开关、PTT 键和选择器、toggle 键和选择器、实时胶囊预览、自动粘贴(内联辅助功能提示);
• Transcription:Whisper 模型选择器(Base / Small / Medium / Large / Turbo)与语言锁。五个 Whisper 仓库映射在 WHISPER_HF_REPOS 可直接核对;
• Refinement:自动精炼开关、模型选择器、smart cleanup、remove self-corrections、preserve technical terms;
• Playback:Captures tab "Play as" 动作的默认语音,分叉按钮选择会跨 tab 切换与重启持久化;
• Storage:captures 文件夹快速打开。

7.6 Stories:时间线编辑器升级

Stories tab 从 TTS 排序器毕业成真正的时间线编辑器(同一生成行底座,但剪辑可组合):

• 导入外部音频:拖音乐文件进 story 内容区,或从新增的 "Import audio" 入口选;接受 wav / mp3 / flac / ogg / m4a / aac / webm,上限 200 MB(与 MCP 转写的 200 MB 上限一致)。导入剪辑显示文件名而非档案名,并跳过 regenerate / 版本选择器——没有可重新生成的东西。
• 逐剪辑音量:剪辑工具栏的 Volume2 图标打开 0–200% 滑块,实时生效且作用于导出;split 与 duplicate 会继承音量。
• Regenerate:剪辑聊天列表下拉与轨道编辑器工具栏都能触发,走与 History tab 相同的生成路径,完成状态进全局 pending 集合。
• 轨道增删:时间线最上方标签格顶部与最下方底部的小 + 条,可加空轨道,粘附在标签列随行内横向滚动。
• 缩放条跟随工程:最小视野 10 秒(放大上限)、最大为整个工程(缩小上限)、默认 60s;+/− 按钮与滚动条边缘拖拽都被夹在动态边界内。

7.7 界面与 Windows 对等

• 主题选择器:Light / dark / system,Settings → General 持久化,System 模式监听 OS 外观变化实时翻转;
• 可拖动波形播放器:捕获详情卡嵌入 WaveSurfer 波形,点击寻址 + 当前/总时长时间戳对,取代静态时长标签;
• 捕获胶囊浅色模式:独立浅色调色板,亮色窗口背景下仍可读;
• 就绪清单:与 Captures 空状态相同的六门清单镜像进 Settings → Captures,防止"红色门被绿色开关藏住";全绿后隐藏;macOS 专属行(Input Monitoring、Accessibility)在 Windows/Linux 上完全隐藏;
• Windows 对等:同样的听写流程,右手侧默认键和(Ctrl+Shift)避开 AltGr 布局冲突;焦点在热键按下时捕获,保证粘贴落回原始输入框即使转写/精炼期间焦点漂移。

7.8 Unreleased(文档时点)

CHANGELOG 顶部的 Unreleased 段记录了一组 Linux ROCm 改进:Docker ROCm 构建在安装依赖时保持 PyTorch 走 ROCm 轮子索引(防止后续安装替换成 CUDA 轮子);ROCm compose 覆盖层不再假设 Ubuntu 的 render/video 组 ID,改为启动时加入拥有 GPU 设备节点的组(对应 docker-compose.rocm.yml);原生 Linux 安装按 GPU 厂商在装后端依赖前先选 ROCm(AMD)或 CUDA(NVIDIA)轮子。

八、工程实践:从 CHANGELOG 本身能学到什么

把整份 CHANGELOG.md 当工程文档读,还有三点跨版本沉淀的实践值得开发者借鉴:

1. 版本注释即发布管线文档。文件头四行注释声明了自动编译机制与两个 agent skill(draft-release-notes、release-bump)的职责边界;CI 发布工作流从 CHANGELOG.md 抽取 Release Notes;Docker web 构建专门把 CHANGELOG.md 打进镜像让应用内 Changelog 页可用。一份文件同时服务人类、CI 与产品 UI 三套消费方。
2. 热修叙事保留因果链。0.4.2 → 0.4.4 → 0.4.5 的离线模式三部曲没有用"修复了若干问题"糊过去,而是把每一版的守卫为何引入、为何引发回归、为何在 0.4.5 用包装器根治写清楚了——这正是当前 hf_offline_patch.py 存在的原因说明,读代码前先读这段能少走很多弯路。
3. 规格表与源码注册表对齐。0.2.1 的引擎表、0.5.0 的 Qwen3 三档 LLM 规格,都能在 backends 包入口的 ModelConfig 注册表 里逐条对到 size_mb 与 languages 字段;Whisper 五档对应 WHISPER_HF_REPOS;捕获默认键和对应 capture_chords.py。这种"changelog 与代码同构"的状态,是验证本文所有引用的最便捷方式。

适用前提与限制:本文所有结论基于当前仓库快照;CHANGELOG 中标注的日期、模型体积与速度数据是文档原文记载,其中模型体积(如 TADA 1B 约 4 GB、Kokoro 82M 约 350 MB)以 ModelConfig 的 size_mb 字段为准;0.4.2 明确记载 Linux 桌面构建当时仍暂停,Unreleased 段的 ROCm 改进主要面向 Docker 与原生安装路径;MCP 的 voicebox.transcribe 绝对路径模式仅对 loopback 调用方开放,这是刻意的安全边界而非缺陷。