Hex常见问题解答：解决你的语音转文字难题

【免费下载链接】HexVOICE → WORDS项目地址: https://gitcode.com/gh_mirrors/hex15/Hex

Hex 是一款专为 macOS 打造的语音转文字工具，它的核心体验是"按住说话、松开出字"：按下热键说出内容，松开后语音转文字结果便自动粘贴到光标所在位置。本文汇总了新手使用 Hex 时最常遇到的 8 类问题与解决方案，帮助你快速上手这款 macOS 语音转文字工具，告别卡壳与报错。

1. Hex 是什么？语音转文字工具如何工作？

Hex（项目描述：VOICE → WORDS）是一款常驻菜单栏的全局语音输入工具。它通过全局热键监听键盘事件，按下热键即开始录音，松开热键后调用本地 AI 模型完成语音转文字，并把结果直接"粘贴"到任意应用中——无论是聊天窗口、文档编辑器还是邮件，都能即说即得。

它提供两种录音模式：

两种模式的判定逻辑由 HotKeyProcessor.swift 实现，热键的具体按键组合配置见 HotKey.swift。

2. 系统要求与安装方法：我的电脑能用吗？

这是最常被问到的问题。Hex 目前仅支持 Apple Silicon（M1 及更新芯片）的 Mac，Intel 机型暂无法使用。系统版本建议 macOS 14（Sonoma）及以上。

安装有两种最便捷的方式：

• Homebrew 一键安装：brew install --cask kitlangton-hex
• 官网下载安装包：从项目发布页获取最新的.dmg安装包

如果你希望查看或参与源码，也可以通过git clone https://gitcode.com/gh_mirrors/hex15/Hex获取完整工程。项目由 Swift + SwiftUI 编写，核心逻辑集中在HexCore/Sources/HexCore/目录下，适合对 macOS 开发感兴趣的读者阅读。

3. 首次启动：麦克风与辅助功能权限怎么授予？

首次打开 Hex，必须授予两项系统权限，缺一不可：

1. 麦克风权限：用于录制你的声音。请在"系统设置 → 隐私与安全性 → 麦克风"中勾选 Hex。
2. 辅助功能（Accessibility）权限：用于让 Hex 把转写文本自动粘贴到任意应用中。请在"系统设置 → 隐私与安全性 → 辅助功能"中启用 Hex。

授予权限后，建议完全退出 Hex 再重新打开，确保权限生效。如果热键一直没反应，优先检查辅助功能权限是否已勾选。

4. 热键不生效怎么办？如何正确设置热键？

热键是 Hex 的"扳机"，设置不当会导致无法触发录音。常见原因与解决办法如下：

• 权限未生效：重新检查辅助功能权限，必要时移除后重新添加。
• 热键冲突：选择的组合键被其他软件（如输入法、截图工具）占用，建议更换为Option、⌥+K这类不常用组合。
• 误触被拦截：Hex 对"修饰键单独作为热键"（如单独按 Option）设置了 0.3 秒的保护阈值，快速点按会被视为误触而静默忽略。这是为了防误触而刻意设计的行为，按住超过 0.3 秒即可正常录音。
• 唤醒后失效：在睡眠唤醒后热键偶尔失灵，可重启 Hex 或重新勾选权限。

详细的判定时间线与阈值说明可参考项目文档 hotkey-semantics.md，源码实现在 HotKeyProcessor.swift。

5. 录音没有声音或转写失败，如何排查？

"按了热键却没反应"或"转写结果为空"通常来自以下三方面：

• 麦克风选错设备：在设置中检查是否选择了正确的输入设备，尤其是外接耳机或声卡时。Hex 在音频设备变化时会自动重建采集引擎，但偶尔需要手动切换一次麦克风。
• 录音时间过短：快速点按热键产生的超短音频（小于 0.2~0.3 秒）会被视为误触丢弃，这是正常的防抖逻辑。请确保按住热键说出完整内容后再松开。
• 模型未下载完成：首次使用需要下载语音转文字模型，若模型尚未就绪会直接跳转到模型设置页。请到设置中的模型库（Model Library）完成下载后再试。

相关录音逻辑见 RecordingClient.swift，转写调度见 TranscriptionFeature.swift。

6. 转写结果不准确，怎么提升识别率？

转写准确度与所选 AI 模型直接相关。Hex 内置两套本地模型：

• Parakeet TDT v3（默认推荐）：速度快、支持多语言，云端优化过的推理模型，日常使用首选。
• WhisperKit（Whisper 系列）：完全离线运行，支持 Tiny、Base 直到 Large v3 Turbo 多种规格，追求更高准确率可选用 Large v3 Turbo，体积约 632MB，但速度比 Small 快数倍。

建议按"速度优先选 Parakeet，准确率优先选 Whisper Large"的原则选择。模型管理代码见 ModelDownloadFeature.swift。

此外，口音较重时，可通过单词映射功能自定义纠错：把常被识别错的词替换为正确写法，规则定义在 WordRemapping.swift。

7. 如何让输出文本更规范？格式化技巧汇总

Hex 内置了实用的文本后处理功能，帮你"出口成章"：

• 自动小写：适合输入代码注释、变量名等场景。
• 去除标点：一键去掉输出中的逗号句号，适合短语速记。
• 单词移除：设置关键词自动从结果中删除，例如去掉口头禅"那个""就是"。
• 单词映射：支持转义符\n、\t，可把识别结果自动插入换行或制表符。

格式化逻辑见 TranscriptFormatting.swift，单词移除规则见 WordRemoval.swift。

8. 常见问题速查表（FAQ 汇总）

结语

Hex 把"语音转文字"做到了极致简单——按下、说话、松开，文字即达。大多数问题都源于权限与热键配置，按照本文的排查步骤操作，几分钟内就能流畅使用。如果遇到文中未覆盖的问题，欢迎在项目仓库提交 Issue 反馈，或查看根目录的 README.md 与 CHANGELOG.md 了解最新版本动态。

【免费下载链接】HexVOICE → WORDS项目地址: https://gitcode.com/gh_mirrors/hex15/Hex