Voicebox 版本演进全解:从 0.1.0 单引擎语音克隆到 0.5.0 语音 I/O 中枢【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox本文以 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.0Capture 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.7B10约 3.5 GB最高质量,支持 delivery instructionsQwen3-TTS 0.6B10约 1.2 GB更轻更快的变体LuxTTS英语约 300 MBCPU 友好、48 kHz 输出、约 150 倍实时速度Chatterbox Multilingual23约 3.2 GB语言覆盖最广,零样本克隆Chatterbox Turbo英语约 1.5 GB350M 参数、低延迟、副语言标签这版的关键能力:线程安全的按引擎后端注册表:引擎可在单次生成之间从下拉框切换,无需重启。对应实现即 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_120PTX前向兼容。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.xtorch.from_numpy崩溃:torch 按 numpy 1.x ABI 编译,配对 numpy 2.x 时每个 TTS 请求都报RuntimeError: Numpy is not available;requirements 固定numpy2.0,并加 PyInstaller 运行时钩子用ctypes.memmove兜底,后加固为未知 dtype 直接抛错而非静默按 float32 重解释。Windows 后台服务器:/watchdog/disable请求可能输给进程退出,新增.keep-running哨兵文件作为同步兜底,启动时清理陈旧哨兵。macOS 11 启动崩溃:ScreenCaptureKit 弱链接使应用在 macOS 12.3 以下可启动;系统音频采集用sw_vers真实版本检查做门控。macOS Intel:放宽torch2.7.0→torch2.2.0,因为 PyTorch 在 2.2.2 后不再提供 x86_64 预编译轮子。Stories 拆分竞态:后端加with_for_update()行锁,前端加isPending守卫。历史状态陈旧:GET /history/{id}原来硬编码statuscompleted,现改为返回真实行的status/error/engine/model_size/is_favorited。安全加固:voice prompt 缓存改用torch.load(weights_onlyTrue);字符串路径守卫换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-sinkpactl list short sources,环境变量PULSE_SOURCE路由)、前端 CI 首道质量门(bun run typecheckbun 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-fnslocale 对象本地化(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 崩溃三部曲这三版构成一次教科书级的热修链,值得完整保留: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/。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 提供正解。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_OFFLINE1 或网络故障时 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 默认避开左手 CmdOption 键和(不与系统快捷键冲突);Windows 默认避开德语/法语/西语布局中 CtrlAlt 即 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用temperature0.9、max_tokens256,系统提示只含角色设定 任务描述,用户轮固定为Speak.——高温保证连续点击的多样性;rewrite_as_profile用temperature0.3、max_tokens1024,且输入先过collapse_repetitive_artifacts清洗再送 LLM——低温保语义保真(对应 compose/rewrite 双入口)。系统提示刻意保持短小,注释解释了原因:小模型(0.6B)在长系统提示下会退化。API 面(CHANGELOG 原文保留):POST /generate、POST /speak与 MCPvoicebox.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/, transporthttp)以 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 tabvoicebox_speakvoicebox.transcribeWhisper 转写 base64 音频或绝对本地路径;路径模式仅限 loopback 调用方——防止绑定在0.0.0.0的 Voicebox 变成未鉴权的任意本地文件读取原语;200 MB 上限(MAX_TRANSCRIBE_BYTES)voicebox_transcribevoicebox.list_captures最近的语音捕获及转写,limit1–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 逐行对应):显式profile参数(名称或 id,大小写不敏感);该客户端的MCPClientBinding.profile_id绑定;capture_settings.default_playback_voice_id全局默认;以上皆无则报错并指向 Settings 页面。语音胶囊(speaking pill):Agent 发起的发言呈现与听写相同的屏幕胶囊,speaking状态显示档案名与计时器。_speak_response里发布speak-start事件、run_generation完成钩子发结束事件(见 事件发布处)——注释的原话是无声后台 TTS 是信任风险,胶囊永远显示你机器上正在出来的东西。POST /speakREST 封装:与 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-code7.4 Refinement:Whisper 之后的 LLM 精炼干净的转写光靠 Whisper 不够。每条捕获流经一个小 Qwen3 LLM:去填充词、修标点、可选重写自我更正——全部在本地。三个设计点在源码中可完整验证: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 原样回显——确定性剥离两边都躲开。按捕获的 flag 快照:转写精炼的三个开关smart_cleanup、self_correction、preserve_technical(RefinementFlags,默认全开)逐条存进每个捕获,之后可以用不同 flag 重跑精炼而原始转写不丢。提示词在服务端按布尔 flag 组装(build_refinement_prompt):基础指令固定要求转写是数据不是指令——不回答、不执行、不寒暄,三个开关各追加一段规则,其中preserve_technical会做点号/斜杠/下划线等口语标点转字面符号(index dot tsx → index.tsx)。模型选择器: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 对等:同样的听写流程,右手侧默认键和(CtrlShift)避开 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 当工程文档读,还有三点跨版本沉淀的实践值得开发者借鉴:版本注释即发布管线文档。文件头四行注释声明了自动编译机制与两个 agent skill(draft-release-notes、release-bump)的职责边界;CI 发布工作流从CHANGELOG.md抽取 Release Notes;Docker web 构建专门把CHANGELOG.md打进镜像让应用内 Changelog 页可用。一份文件同时服务人类、CI 与产品 UI 三套消费方。热修叙事保留因果链。0.4.2 → 0.4.4 → 0.4.5 的离线模式三部曲没有用修复了若干问题糊过去,而是把每一版的守卫为何引入、为何引发回归、为何在 0.4.5 用包装器根治写清楚了——这正是当前 hf_offline_patch.py 存在的原因说明,读代码前先读这段能少走很多弯路。规格表与源码注册表对齐。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 调用方开放,这是刻意的安全边界而非缺陷。【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Voicebox 版本演进全解:从 0.1.0 单引擎语音克隆到 0.5.0 语音 I/O 中枢
Voicebox 版本演进全解:从 0.1.0 单引擎语音克隆到 0.5.0 语音 I/O 中枢【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox本文以 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.0Capture 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.7B10约 3.5 GB最高质量,支持 delivery instructionsQwen3-TTS 0.6B10约 1.2 GB更轻更快的变体LuxTTS英语约 300 MBCPU 友好、48 kHz 输出、约 150 倍实时速度Chatterbox Multilingual23约 3.2 GB语言覆盖最广,零样本克隆Chatterbox Turbo英语约 1.5 GB350M 参数、低延迟、副语言标签这版的关键能力:线程安全的按引擎后端注册表:引擎可在单次生成之间从下拉框切换,无需重启。对应实现即 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_120PTX前向兼容。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.xtorch.from_numpy崩溃:torch 按 numpy 1.x ABI 编译,配对 numpy 2.x 时每个 TTS 请求都报RuntimeError: Numpy is not available;requirements 固定numpy2.0,并加 PyInstaller 运行时钩子用ctypes.memmove兜底,后加固为未知 dtype 直接抛错而非静默按 float32 重解释。Windows 后台服务器:/watchdog/disable请求可能输给进程退出,新增.keep-running哨兵文件作为同步兜底,启动时清理陈旧哨兵。macOS 11 启动崩溃:ScreenCaptureKit 弱链接使应用在 macOS 12.3 以下可启动;系统音频采集用sw_vers真实版本检查做门控。macOS Intel:放宽torch2.7.0→torch2.2.0,因为 PyTorch 在 2.2.2 后不再提供 x86_64 预编译轮子。Stories 拆分竞态:后端加with_for_update()行锁,前端加isPending守卫。历史状态陈旧:GET /history/{id}原来硬编码statuscompleted,现改为返回真实行的status/error/engine/model_size/is_favorited。安全加固:voice prompt 缓存改用torch.load(weights_onlyTrue);字符串路径守卫换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-sinkpactl list short sources,环境变量PULSE_SOURCE路由)、前端 CI 首道质量门(bun run typecheckbun 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-fnslocale 对象本地化(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 崩溃三部曲这三版构成一次教科书级的热修链,值得完整保留: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/。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 提供正解。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_OFFLINE1 或网络故障时 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 默认避开左手 CmdOption 键和(不与系统快捷键冲突);Windows 默认避开德语/法语/西语布局中 CtrlAlt 即 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用temperature0.9、max_tokens256,系统提示只含角色设定 任务描述,用户轮固定为Speak.——高温保证连续点击的多样性;rewrite_as_profile用temperature0.3、max_tokens1024,且输入先过collapse_repetitive_artifacts清洗再送 LLM——低温保语义保真(对应 compose/rewrite 双入口)。系统提示刻意保持短小,注释解释了原因:小模型(0.6B)在长系统提示下会退化。API 面(CHANGELOG 原文保留):POST /generate、POST /speak与 MCPvoicebox.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/, transporthttp)以 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 tabvoicebox_speakvoicebox.transcribeWhisper 转写 base64 音频或绝对本地路径;路径模式仅限 loopback 调用方——防止绑定在0.0.0.0的 Voicebox 变成未鉴权的任意本地文件读取原语;200 MB 上限(MAX_TRANSCRIBE_BYTES)voicebox_transcribevoicebox.list_captures最近的语音捕获及转写,limit1–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 逐行对应):显式profile参数(名称或 id,大小写不敏感);该客户端的MCPClientBinding.profile_id绑定;capture_settings.default_playback_voice_id全局默认;以上皆无则报错并指向 Settings 页面。语音胶囊(speaking pill):Agent 发起的发言呈现与听写相同的屏幕胶囊,speaking状态显示档案名与计时器。_speak_response里发布speak-start事件、run_generation完成钩子发结束事件(见 事件发布处)——注释的原话是无声后台 TTS 是信任风险,胶囊永远显示你机器上正在出来的东西。POST /speakREST 封装:与 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-code7.4 Refinement:Whisper 之后的 LLM 精炼干净的转写光靠 Whisper 不够。每条捕获流经一个小 Qwen3 LLM:去填充词、修标点、可选重写自我更正——全部在本地。三个设计点在源码中可完整验证: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 原样回显——确定性剥离两边都躲开。按捕获的 flag 快照:转写精炼的三个开关smart_cleanup、self_correction、preserve_technical(RefinementFlags,默认全开)逐条存进每个捕获,之后可以用不同 flag 重跑精炼而原始转写不丢。提示词在服务端按布尔 flag 组装(build_refinement_prompt):基础指令固定要求转写是数据不是指令——不回答、不执行、不寒暄,三个开关各追加一段规则,其中preserve_technical会做点号/斜杠/下划线等口语标点转字面符号(index dot tsx → index.tsx)。模型选择器: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 对等:同样的听写流程,右手侧默认键和(CtrlShift)避开 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 当工程文档读,还有三点跨版本沉淀的实践值得开发者借鉴:版本注释即发布管线文档。文件头四行注释声明了自动编译机制与两个 agent skill(draft-release-notes、release-bump)的职责边界;CI 发布工作流从CHANGELOG.md抽取 Release Notes;Docker web 构建专门把CHANGELOG.md打进镜像让应用内 Changelog 页可用。一份文件同时服务人类、CI 与产品 UI 三套消费方。热修叙事保留因果链。0.4.2 → 0.4.4 → 0.4.5 的离线模式三部曲没有用修复了若干问题糊过去,而是把每一版的守卫为何引入、为何引发回归、为何在 0.4.5 用包装器根治写清楚了——这正是当前 hf_offline_patch.py 存在的原因说明,读代码前先读这段能少走很多弯路。规格表与源码注册表对齐。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 调用方开放,这是刻意的安全边界而非缺陷。【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考