Hex 2.3.0 版本解析:Windows 公测、全平台流式听写与统一设置面板
Hex 2.3.0 版本解析:Windows 公测、全平台流式听写与统一设置面板
Hex 2.3.0 是一次跨越平台形态的发布:桌面端首次提供 Windows x64/ARM64 公测,macOS、Linux、Windows 三端共享同一套流式听写(streaming dictation)通路,并把英文听写默认模型一次性迁移到 Parakeet Unified English。本文以 2.3.0 发布说明 为骨架,逐条拆解每项变更的用户可见行为、可配置项与仓库中的实现依据,帮助你在升级前后快速验证与排障。
版本速览
发布说明本身很短,但它对应的构建信息在仓库其他地方有明确记录:
| 项目 | 2.3.0 的实际值 | 依据 |
|---|---|---|
| macOS 构建号 | 20300 |
发布说明、发布验证记录 |
| 发布提交 | cfb4eb4(在 #155 e849fa4、#160 41fb3e2 之上合并 #161) |
发布验证记录 |
| 公开发布日期 | 2026 年 10 月 19 日(macOS) | 发布验证记录 |
| 公共 TypeScript SDK | 仍为 0.3.1 |
发布说明、sdk/typescript/package.json |
这里有两个关键信息:其一,2.3.0 的 macOS 包与 SDK 版本号是解耦的,SDK 不随桌面端同步跳版本;其二,Linux 与 Windows 2.3.0 是单独发布与验证的,发布验证记录明确写到「未在 Linux 或 Windows 硬件上执行安装器运行、自更新或听写」,因此跨平台的实机行为需要你在自己机器上按后文的检查项验证。
Windows 公测:托盘常驻、Vulkan 与 CPU 双路径
发布说明给出的 Windows 形态是:按住 Ctrl+Space 在任意应用中听写,Hex 常驻系统托盘、随登录启动,并从签名发布中自更新。
为什么 x64 用 Vulkan,ARM64 用 CPU
这不是简化,而是由推理后端决定的。按 docs/windows.md 的说明:
- x64 通过 Vulkan 在 GPU 上解码,需要较新的 NVIDIA / AMD / Intel 显卡驱动(驱动提供
vulkan-1.dll);安装器检测不到时会带说明中止。 - ARM64 在 CPU 上解码。
- 两个架构都是自包含的,不需要 Visual C++ Redistributable。
同样的说法在流式听写章节被再次强调:CPU 设备(包括 ARM64)始终走整段转写路径,即 source=offline,不做流式增量解码。这解释了为什么「Windows 也能流式听写」这句话只在 x64 + GPU 前提下成立。
安装与设置落盘位置
安装器不需要管理员权限,按当前用户安装,会自动加入开始菜单与「设置 › 应用」,卸载时清理所有已安装版本、快捷方式与登录启动项,但保留 %APPDATA%\hex 下的设置、日志、历史与模型。设置文件路径为 %APPDATA%\hex\settings.json,与 macOS、Linux 使用同一份 schema。
源码构建则要求 64 位 Windows 10/11、PowerShell 7 或 5.1、winget、Visual Studio C++ Build Tools、CMake 与稳定版 MSVC Rust 工具链;x64 还需要 Vulkan SDK 并设置 VULKAN_SDK。ARM64 由于 ggml 的 ARM CPU 后端拒绝 MSVC,需要用 clang-cl + Ninja 构建,并关闭 GGML_NATIVE:
# 来自 docs/windows.md 的 ARM64 构建约束
# CC=clang-cl
# CXX=clang-cl
# CMAKE_GENERATOR=Ninja
# TRANSCRIBE_CMAKE_ARGS=-DGGML_NATIVE=OFF -DGGML_OPENMP=OFF
GGML_NATIVE=OFF 不只是 ARM64 的问题:分发构建同样需要它,否则 ggml 会把 CPU 内核优化到构建机指令集上,二进制在较老的 CPU 上可能直接崩溃。
启动即用的验收动作
安装后有三步可以确认 Windows 侧真的跑通:
cargo run -- devices # 列出 WASAPI 输入设备
cargo run -- model devices # 列出 transcribe.cpp 可见的计算后端
cargo run -- model install # 安装默认英文模型
cargo run -- model check # 加载并自检
cargo run -- model transcribe .\sample.wav
设置卡片显示 Enabled 表示快捷键在全系统生效,Disabled 表示不生效;托盘里的 Enable / Disable Hex 与它联动。修改模型、麦克风、听写快捷键、双击行为或 Paste Last 时,监听器会自动重启,不需要先手动停止。
全平台流式听写:边说话边解码
这是 2.3.0 最核心的体验变更。发布说明的表述是:在 macOS、Linux、Windows 上,Hex 在你说话时就进行转写,于是松开快捷键后约十分之一秒就能完成,无论你说了多久;一次 2 分钟的听写在 RTX 5070 Ti 上从 0.9 秒降到 0.1 秒,在 MacBook Air M4 上从 2.8 秒降到 0.1 秒。
一次流式听写的完整时序
docs/features/dictation.md 的 «Streaming Finish» 小节给出了可逐帧对照的流程:
Model advertises streaming, GPU device // 模型声明 streams 且设备为 GPU
Load or switch model -> Probe a one-second silent stream // 探针,同时预热计算图
├── Succeeds -> Stream shortcut captures
└── Fails, CPU device, Apple Speech, or HEX_STREAMING=0 -> 仅整段路径
Shortcut capture passes the hold threshold(Hold 模式;Toggle 在 Windows/Linux 上为按下即开始)
-> Open one live stream;喂入 16 kHz 积压音频,之后每 160 ms 喂一次
Release -> 收集 200 ms 尾音 -> Finish with the complete clip
-> 喂入剩余音频 -> Finalize -> 最终文本
├── 流失败、无文本、或超出剪辑 250 ms 以上 -> 整段离线转写(source=fallback)
├── 1.5 秒内没有最终文本 -> 中止流 -> 整段转写
└── 录制期间切换了模型 -> 关闭流 -> 整段转写
Short tap、Escape、和弦丢弃、麦克风失效 -> 丢弃流
几个容易被忽略但很关键的约束:
- 流打开前有探针。加载或切换模型时先用一秒静音流探测,这既判断能力也预热 compute graph,避免第一次真实听写被冷启动拖慢。
- 喂入的音频与最终剪辑一致。包含 pre-roll,保证流式结果和整段结果的音频前缀相同;仓库里有
recorded_audio_is_a_prefix_of_the_finished_clip(16 / 44.1 / 48 kHz)与resampled_clips_keep_the_last_word_through_a_delayed_release等测试覆盖这一点。 - 最终文本没出现之前不会粘贴。发布说明强调「流式失败就整段转写,什么都不会丢」,对应的实现是三条明确回退条件(失败 / 无文本 / 超时 1.5 秒),以及模型中途被切换时关闭流。
Parakeet 的分块参数
流式并非任意切分。文档给出的 Parakeet 缓冲配置是它的最大上下文窗口:Unified English 为「左侧 5.6 秒、块 1.04 秒、右侧 1.04 秒」,这是一个在准确率与算力之间取的平衡点。文档还记录,把块改小到 560 ms 或 160 ms 只会增加错误并让 GPU 占用多出最多 20%,换不到更快的回落速度。
可观测性与调参环境变量
每次听写都会在 logs/process.log(Windows)或对应平台的日志目录里写入:
| 字段 | 取值 | 含义 |
|---|---|---|
source |
stream |
流式完成 |
source |
offline |
整段转写(CPU、Apple Speech、或显式关闭流式) |
source |
fallback |
流失败/超时后回退整段 |
finish_ms |
毫秒 | 从松手到出文本的耗时 |
调试用的环境变量在 docs/windows.md 与 docs/features/dictation.md 中都有记录:
HEX_STREAMING=0:强制整段路径,用于对照实验。HEX_STREAMING=1:在任何设备(含 CPU)上启用流式,仅用于诊断与 Linux CI 夹具。HEX_STREAM_CHUNK_MS:覆盖分块长度,用于基准测试,不建议日常使用。
仓库里还有一个真实的端到端夹具 scripts/test-linux-dictation.sh:把同一段语音通过虚拟麦克风重放两次,一次在 CPU 上走整段(期望 source=offline),一次带 HEX_STREAMING=1(期望 source=stream,或 CPU 流错过截止时间时 fallback)。这是验证「回退确实生效」最省事的办法。
英文模型的一次性迁移
发布说明的第三条是本版本最需要理解清楚的「有条件的自动行为」:
如果已经下载了 Parakeet Unified English,就把英文听写切换到它一次;之前的模型仍然留在本地,在 Settings › Local transcription 里一键可回;如果没有下载 Parakeet Unified,或者你在用别的语言听写,就保留你原来的模型。
源码中的迁移判定
这条逻辑对应 src/app_settings.rs 中的一次迁移器:
const STREAMING_ENGLISH_MIGRATION: &str = "streaming-english-model";
apply_one_time_migrations 会检查 migrations 数组里是否已有该 ID,没有则调用 switch_english_to_streaming_model,随后把 ID 写回,保证「之后再手动切回旧模型」不会被下一次启动覆盖。迁移函数的三道门是:
- 当前语言必须是
"en",且当前模型不是ParakeetUnifiedEnglish; - 目标模型必须已安装(通过
transcription_models::is_installed(model, "en")判断),因此升级不会把用户卡在下载等待里; - 新选择要能通过
validate,否则放弃迁移。
迁移成功后日志会记录 switched English dictation to the streaming English model,并把新选择写入 recents,从而保留「一键回退」入口。这套设计在测试里也有明确断言:new_settings_need_no_one_time_migration 保证全新配置不会触发迁移,另有测试验证「切回之后不会被再次迁移」。
为什么只迁移英文
因为 Parakeet Unified English 是纯英文模型。src/transcription_models.rs 中语言路由对 "en" 的首选就是它:
(ParakeetUnifiedEnglish, Recommended),
其他语言走各自的推荐项(例如德语、芬兰语、瑞典语等走 Whisper turbo,马耳他只走 Parakeet v3)。这意味着迁移逻辑把「语言不匹配」的判断放在最前面,而不是靠模型自身的可用性兜底。
遗留字段的兼容性
migrations: Vec<String> 带有 #[serde(default)],缺失时反序列化为空数组 —— 于是老配置文件会被视为「尚未执行过任何迁移」,这正是迁移「只跑一次且对老用户生效」的机制基础。shortcut_mode 也是同样的思路:缺少该字段的旧文件按 Hold 加载(测试 shortcut_mode_defaults_to_hold_and_round_trips)。
模型选择器:Streams 标签、Recommended 与活动圆点
发布说明里这条看起来是 UI 细节,但它决定用户如何判断「哪个模型能边说话边出字」:
- 能流式的模型在卡片上带 Streams 标签;
- 你选中它之后,Recommended 标签不会消失;
- 当前生效的模型用圆点而不是徽章表示。
三者在 src/rune_ui/picker.rs 中实现得很直白:if model.streams { title = title.child(Badge::new(tr("Streams")).build(p.k)); } 与推荐标签并行追加,活动态用 super::controls::status_dot(p.accent()) 绘制。当前只有一项模型的 streams 为 true,测试 only_the_buffered_parakeet_artifact_is_marked_streaming 直接断言了这个集合只包含 ParakeetUnifiedEnglish —— 也就是说 Streams 标签是能力声明,不是营销文案。
多语言界面下这个标签会被翻译("Streams" 在中文为「流式」,见 src/desktop_i18n.rs),所以截图对照时请以英文界面为准。
移除 Transcribe during pauses
发布说明只写了一行:「Removes Transcribe during pauses: streaming replaces it.」要理解它,需要回看 2.2.0 的发布说明:该设置(Settings › Behavior,默认开启)做的是「在你停顿的时候把已完成的语音先转写掉,于是松手时只需要转写最后几秒」,属于在整段路径上做的分段优化。
2.3.0 用真正的增量流式替代了它,两者解决同一问题但机制不同:前者按「停顿」切分、依赖 VAD 式判断;后者按固定块持续喂入同一个流。文档因此明确写道:macOS 的 “Transcribe during pauses” 设置不再影响听写行为。升级后你会看到这个开关消失,这是预期行为,不是功能回退。
需要注意的边界:流式在 CPU 设备上不启用,此时 Hex 回到整段转写。如果你之前在低配或纯 CPU 机器上依靠「停顿转写」获得较快回落,2.3.0 之后这类设备的体验回到整段延迟,这是本次替换的代价。
Chromium 粘贴修复:定位到具体版本再绕开
发布说明写到:修复了在 Chrome 155 和 156,以及 Brave、Arc、Edge 等 Chromium 浏览器里听写粘贴为空白的问题。
这不是「加点延时」能解决的。src/paste.rs 的注释说明了根因:macOS 上 Chromium 155/156 会丢弃一个与其自身剪贴板变更通知竞争的 ⌘V,无论 Hex 提前等多久都没用;该问题由 Chromium CL 8217390 引入,在 157 的 CL 8503629 中修复。
于是实现策略是「按浏览器大版本判定,改用逐字键入」:
const CLIPBOARD_RACE_CHROMIUM: RangeInclusive<u32> = 155..=156;
has_clipboard_race(bundle) 扫描目标 App 包内的 Contents/Frameworks/<Name> Framework.framework/Versions/<major>.<minor>.<build>.<patch>/,任何一个版本命中 155 或 156 就判定为受影响。注释解释了为什么用「任何一个」:浏览器可能已经暂存了新版本的框架但尚未重启,两个版本中任一命中都要覆盖。命中时不再走剪贴板,而是调用 keyboard::type_text,并记录 typing instead of pasting into Chromium 155 or 156。
工程上的两个细节值得借鉴:其一,判定只读框架目录名,不依赖可执行文件路径,因此对 Chrome、Helium、Brave、Edge、Chromium 本身及多数分叉都成立;其二,逐字键入在任何版本上都能工作,所以「误判」的代价只是慢一点,不会引入新的失败模式。
会议:不要把扬声器里的对方当成「你」
发布说明的这条包含两个修复:在扬声器外放通话时,不再把对方的语音标注为 You;录制会议时的 CPU 占用大幅降低。
第一条的实现思路可以从 src/meeting_echo.rs 的模块注释读出来:当通话从扬声器外放时,麦克风会在系统音轨之后几十毫秒听到同一段远端音频,于是 Hex 在同一时间轴上按 20 ms 帧比较两条轨的能量,判断某段麦克风音频是 bleed(可由「延迟 + 衰减的系统音频」解释)还是 local speech(无法被解释,属于本人在说话)。
几个阈值说明了它的保守程度:远端活动门限 SYSTEM_ACTIVE_DB = -55.0、本地语音需高出预测 bleed 泄漏 LOCAL_MARGIN_DB = 9.0、一段音频中本地成分不超过 20% 判为 bleed、不低于 50% 判为本地语音;同时还用一秒窗口内的活跃帧数处理「一段整体是泄漏、但里面夹着本人插话」的双讲场景。耦合增益会在 60 秒音频上下文中重新估计,因为延迟与衰减只随用户设备与摆放变化。
这是一套纯信号层面的方法,不依赖回声消除设备、也不上传音频。相关回放夹具在 src/meeting_echo_replay_tests.rs,可以用 cargo test meeting_echo_replay -- --ignored --nocapture 在真实录音上复现分类结果。
Shortcut mode:Hold 与 Toggle
发布说明为设置项 Settings › Dictation › Shortcut mode 增加了两种模式:按住说(Hold),或按一次开始、再按一次结束(Toggle)。Escape 在任何模式下都取消。
对应枚举很小,但在每个平台复用同一套状态机:
pub enum ShortcutMode {
#[default]
Hold, // 按住说,松开结束
Toggle, // 按一次开始,再按一次结束;Escape 仍可取消
}
来自 src/dictation.rs 的这个定义带 #[derive(Default)] 与 #[serde(rename_all = "snake_case")],所以落盘值就是 "hold" / "toggle"。配置应用时它被折叠成一个全局原子布尔:
SHORTCUT_TOGGLE.store(self.shortcut_mode == crate::dictation::ShortcutMode::Toggle, Ordering::Relaxed);
行为层有三处容易踩到的细节,在 docs/features/dictation.md 中有清楚记录:
- Toggle 复用锁状态:每次按下等价于双击手势的第二次点击,因此双击锁定与「Double-tap only」在 Toggle 下被隐藏并忽略。
- 头 300 ms 内的和弦仍会被丢弃:切换模式不改变「按键组合判断」的时序规则。
- Linux 的按键释放可能永远不到:Hyprland 的 Lua 绑定在 Alt 先抬起时不会发送释放事件(0.56 及其 portal 版本上已观察)。Windows/Linux 的处理是「距上次按下 1 秒或更久的按下视为结束,更短的按下视为按键重复并忽略」,对应测试
a_repeating_held_press_never_finishes_the_capture。
另外,Linux 上的 hex dictation start / stop 会绕过 Hold、Toggle 与双击规则,直接开始/结束录制,toggle 则做当前该做的那件事;这让你可以把命令绑到按键的按下与释放上,自行实现 push-to-talk。
Recording indicator:顶部、底部或隐藏
设置项 Settings › Behavior › Recording indicator 提供三态:屏幕顶部、底部、或不显示。它是一个带 #[repr(u8)] 的枚举:
pub enum IndicatorPosition { Top = 0, Bottom = 1, Hidden = 2 }
这个数值编码被用在跨进程/跨线程的原子传递上:indicator_position() 直接按 1 => Bottom, 2 => Hidden, _ => Top 还原。HUD 侧的 src/rune_hud.rs 在 show() 里做分派——Hidden 时不显示浮层,但仍把实时文本放到原 HUD 所在位置,避免 live-text 一起消失;非 macOS 平台则按 IndicatorPosition::Bottom => (ScreenEdge::Bottom, BOTTOM_OFFSET) 贴边。Linux 监听器侧的 src/linux_rune_hud.rs 用「generation」机制保证旧监听器的上报不再生效,这样切换设置或重启监听时不会残留一个幽灵 HUD。
发布说明还提到 macOS 的 Settings 新增 Software updates 行与 Check now;对应的更新通道设置是 updates.channel(stable / dev / none),且「切换通道不会比较版本号,只提供该通道当前版本,需你在窗口里确认后才安装」。
Interface language:跟随系统或多语言固定
Settings › Application › Interface language 允许固定界面语言,或跟随系统。发布说明列出的语言是 English、Chinese、German、Japanese、Polish、Spanish。
源码的选择表比说明多一项,供对照时留意:
pub(crate) const LANGUAGE_CHOICES: &[(Option<&str>, &str)] = &[
(None, "System"),
(Some("en"), "English"),
(Some("pl"), "Polski"),
(Some("zh"), "中文"),
(Some("ja"), "日本語"),
(Some("de"), "Deutsch"),
(Some("es"), "Español"),
(Some("uk"), "Українська"),
];
也就是说 2.3.0 的实际构建里还包含乌克兰语;docs/windows.md 的平台对照表也写成「English、Polish、Chinese、Japanese、German、Spanish、Ukrainian」。这属于发布说明与实现的措辞差异,不是缺陷。落盘键为 ui_language,None 表示跟随系统;语言解析按主语言子标签匹配,因此 zh-Hans-CN 会落到 zh。未知语言与未翻译的字符串统一回退英文。
Linux 补齐为完整应用
发布说明这条信息量最大,逐项都对应 macOS 已有的能力:
- X11 上带应用规则的 Modes:Wayland 不暴露焦点窗口,因此那里只应用 Global 模式。
- History、麦克风选择、Paste last dictation、Double-tap only、Release microphone while idle。
- While dictating:按住超过 300 ms 后,通过
wpctl(PipeWire)或pactl(PulseAudio)静音默认输出,或经 D-Bus 暂停 MPRIS 播放器;Hex 只恢复自己改动过的部分,短按与和弦不触发。 - 录音指示器在 X11 与 Wayland 上都可用。
- Voice Action:按住
Ctrl-Alt-I录一段指令,配合主选区文本交给 OpenCode,再粘贴结果。
快捷键的获取方式在 Linux 上有三条路径,最终都驱动同一套听写规则:X11 直接 grab;Wayland 通过 GlobalShortcuts portal 向桌面申请(桌面可能授予、改键或拒绝,Settings 的 Desktop shortcuts 会列出结果);以及上面提到的 hex dictation 命令旁路。
视觉刷新与三端一致
发布说明最后两条是设计层面的统一:每个面板使用同一套文字尺寸梯度、按钮与颜色,次级文本可读性提升,标签改为句首大写;Settings、Modes、Voice Action、History 在三个平台上长得一样。
对使用者而言,真正需要关注的是随之而来的设置存储统一:Windows 与 Linux 在首次启动时把设置搬进 settings.json,旧文件保留为备份。三个平台的路径分别是:
| 平台 | 设置文件 | 日志目录 |
|---|---|---|
| macOS | Application Support 下的 settings.json |
~/Library/Application Support/hex/logs/ |
| Windows | %APPDATA%\hex\settings.json |
%APPDATA%\hex\logs\ |
| Linux | Hex 数据目录下的 settings.json |
~/.local/share/hex/logs/(或 $XDG_DATA_HOME 下) |
统一之后,hex settings 这一组命令在三个平台的含义也一致了:键是 settings.json 的点分路径,hex settings list 打印每个键的类型与描述,加 --json 还会带上 choices。与本文直接相关的几个键:
hex settings list --json | grep -E 'shortcut_mode|indicator_position|ui_language'
hex settings set shortcut_mode toggle
hex settings set indicator_position bottom
hex settings set ui_language zh
hex settings set ui_language none # 跟随系统
布尔值接受 on/off、true/false、yes/no、1/0;可选值可用 none 清空。有一个保护性测试 control::settings::tests::every_persisted_setting_has_a_cli_key:新增持久化设置却没有登记 CLI 键时会直接失败,因此上表中的键不会悄悄失效。注意 transcription.model 与 transcription.language 在这里是只读的,请用 hex model use 切换。
升级后的验证清单
把发布说明的每一条落成可执行的检查,升级后按此顺序过一遍即可:
- 确认走的是流式:做一次 30 秒以上的英文听写,然后在日志里搜
source=。看到stream表示流式生效;offline说明当前是 CPU 设备或模型不支持;fallback说明流失败并已安全回退(此时文本仍应完整)。同时看finish_ms是否符合预期。 - 确认迁移结果:打开模型选择器,当前英文模型应带 Streams 且仍显示 Recommended,活动态是圆点;如果你想回退,旧模型仍在列表里可一键选回,且重启后不会被再次迁移。
- 确认 Toggle 与指示器:在 Settings › Dictation 切到 Toggle,按一次开始说话、再按一次结束,中途按 Escape 应取消;在 Settings › Behavior 把指示器切到顶部/底部/隐藏各试一次。
- 确认 Chromium 粘贴:在 Chrome 155/156 或 Brave/Arc/Edge 中粘贴,长句应该逐字键入并完整出现;日志里应出现
typing instead of pasting into Chromium 155 or 156。 - 确认会议标注:用扬声器外放参加一次通话,录制后检查转写里对方发言是否仍被标为 You。
- 确认 Windows 特有项:托盘常驻、随登录启动、签名更新可用;x64 上看
model devices是否列出 Vulkan 后端,ARM64 上source=offline属于预期。
小结
Hex 2.3.0 的技术主线可以概括为三件事:把听写的延迟从「随长度增长」变成「与长度无关」,靠的是探针 + 增量喂流 + 三条明确回退;把平台差异收敛到一套共享契约,Windows 用 WASAPI/Win32/Vulkan、Linux 用 X11/portal/PipeWire,但设置、面板与听写状态机保持一致;把自动行为做成可逆且有据可查,模型迁移只在「已安装 + 英文 + 校验通过」时发生一次,source 与 finish_ms 把每次决策写进日志。逐条对照 docs/releases/2.3.0.md 与本文引用的源码、测试后,你可以对每项变更给出可验证的结论,而不是仅凭发布说明的措辞判断。