企业官网建设流程全解析

Handy 离线语音转文字完整指南：双推理引擎架构与 5 个实用调优技巧

【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy

Handy 是一款免费、开源、完全离线的语音转文字桌面应用：按住快捷键说话，文字直接落到你当前的输入框里，全程不出本机。下面从源码层面拆解它的快捷键状态机、双推理引擎与流式转录实现，并给你 5 条可直接照做的调优建议，读完你就能安装、选型、按需扩展它。

技术栈总览：Tauri + Rust，为什么是两个推理引擎

Handy 的界面是薄壳——设置、模型选择、历史都在 src/components/ 下，用 React 18 + TypeScript + Tailwind CSS v4 搭建，状态用 Zustand 管理，i18next 覆盖 24 种语言。重活全在 Rust 侧：音频 I/O、VAD（语音活动检测，判断音频里是否有人声）、推理和文本注入。最大的设计决策是让 Whisper 系模型与 Parakeet 等模型跑在两套独立推理引擎上，对应不同文件格式和硬件路径：

⚡ 推理后端按平台编译：Windows x86_64 打包 Vulkan 动态后端加多档 CPU 指令集模块，Windows ARM 只编 CPU 静态链接，macOS 编 Metal——全部声明在 Cargo.toml 的 target 段里，用户无需手动装任何 GPU 运行时。

数据流拆解：从按住键到文字粘贴

现象：按住快捷键录音、松手停止；引擎还在处理上一段时你再按新键，状态不会错乱。原理：transcription_coordinator.rs 是按键事件状态机——按下去抖 30ms、松开保留 50ms 宽限期，用来吞掉 X11 自动重复产生的幻影事件；短按（低于 hold_threshold_ms，默认 300ms）记为开关式触发，长按才是推键说话；忙时到达的按键存入 PendingPress，等队列排空后按正确相位续跑，避免"开始录音却永远停不下来"。代码位置：src-tauri/src/transcription_coordinator.rs，默认值定义在 src-tauri/src/settings.rs。

现象：说话时浮层文字逐句长出，已确认的内容从不闪烁回改。原理：流式转录把结果拆成两段——src-tauri/src/managers/transcription.rs 中 StreamTextEvent 的 committed 是只增不改的稳定前缀，tentative 是模型还可能改写的易变后缀，浮层按这两段渲染。是否支持流式由模型能力位决定：Handy 下载前先解析 GGUF 文件头，读 streaming、translate、语言检测和支持语言集等 7 个元数据字段做预判，加载后再与运行时真值对齐。代码位置：src-tauri/src/managers/ 与 src/overlay/。

现象：内存紧张时不用等模型"自己走"。原理：ModelUnloadTimeout 定义了 Never、Immediately、2/5/10/15 分钟、1 小时共 8 档，默认 5 分钟——模型闲置超时即从内存卸载，这是 src-tauri/src/settings.rs 里的显式枚举。

💡 实用技巧：模型选型、粘贴方式与常见坑

1. 只有 CPU 没有 GPU：选 Parakeet V3。它走 ONNX 引擎的 CPU 路径并支持自动语言检测，项目文档标注约 5 倍实时速度且精度不降。
2. 粘贴失败或格式混乱：粘贴策略共 6 种（CtrlV、Direct、ShiftInsert、CtrlShiftV、None、ExternalScript），目标程序拦截 Ctrl+V 时切 Direct 试试。
3. macOS 蓝牙耳机录音时外放变闷：蓝牙耳机切换双向音频所致；输出保留耳机，输入改选 Mac 内置或外置麦克风（README 已知问题一节有说明）。
4. 不点界面遥控 Handy：handy --toggle-transcription远程控制运行中实例的录音启停，handy --cancel取消当前转录，--start-hidden --no-tray配合系统自启可做成纯后台服务。
5. 专业术语总识别错：把术语填进自定义词汇表，转录后按相似度做纠错（word_correction_threshold 默认 0.18），入口见 CustomWords.tsx，实现在 audio_toolkit/ 的 apply_custom_words。

定制与扩展：新增一个功能从哪下手

🧩 想加一个设置项，最短路径是三段式：在 src/components/settings/ 写一个组件，在 src/stores/settingsStore.ts 注册状态，需要后端持久化就在新字段配 serde 默认函数（旧配置文件因此天然兼容）。翻译者直接改 src/i18n/locales/ 下的 JSON 即可，共 24 个语言目录。

src/components/settings/ # 每个设置项一个组件文件 src/stores/settingsStore.ts # 前端状态（Zustand） src-tauri/src/settings.rs # 配置字段与默认值定义 src-tauri/src/managers/ # 音频/模型/转录三大管理器 src-tauri/src/shortcut/ # 快捷键与输入实现 src/i18n/locales/ # 24 语言翻译

Handy 往哪走

Handy 的定位不是"最强的语音转文字"，而是"最可被 fork 的语音转文字"：双推理引擎、按平台编译后端、下载前解析模型元数据，都是在为接入第三方模型和硬件铺路。社区当前重心在新模型支持、跨平台体验打磨与 Raycast 等外部扩展，如果你在做本地 AI 桌面应用，它的"Rust 核心 + 薄 webview 壳"结构值得直接参考。

【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy