一键把语音变文字：Handy 完全离线语音转文本实战解析

一键把语音变文字Handy 完全离线语音转文本实战解析【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款免费、开源、完全离线的语音转文本speech-to-text桌面应用按住一个快捷键说话松开后文字就会出现在你当前聚焦的任意输入框里整个过程不向云端发送任何音频数据。本文从打字太慢这个具体痛点出发先带你跑通安装与上手再逐层拆开它按键 → 录音 → 识别 → 粘贴的完整链路最后给出模型选型、跨平台配置和二次开发的具体建议。从打字太慢到说话成文一个真实场景想象这样一个场景你在写一封长邮件手指敲击键盘的速度远跟不上思路。大多数语音输入方案的解法是把音频上传到云端 API——但这意味着两件事一是断网时功能直接不可用二是你的声音可能包含客户姓名、密钥片段、未发布的产品名离开了你的电脑。Handy 的设计回答就是把整条链路搬回本地。按住快捷键 → 本地录音 → 本地模型推理 → 本地模拟粘贴。它官方的一句话定位很直白不是要成为最好的语音转文本应用而是要成为最容易被 fork 的那一个。场景适配写文档、记会议纪要、填表单、语音输入代码注释以及任何不方便把音频出网的场合比如法务、医疗、企业内网环境。快速上手三平台安装与第一次转录技术要点Handy 基于 Tauri 构建安装包是标准的桌面应用.app / .exe / AppImage、.deb 等无需 Node 或 Python 运行时装完即用。三个平台的最低门槛安装方式macOSbrew install --cask handy或下载 release 安装包Windowswinget install cjpais.Handy注意该 winget 包由社区维护Linux从 release 页下载 AppImage / deb 包启动后依次完成三件事授予麦克风与辅助功能权限macOS 会逐个弹窗申请在 Settings 里确认录音快捷键与行为模式在模型页下载第一个识别模型后文有选型建议快捷键行为提供三种模式对应不同的使用习惯模式行为适合Auto按住录音点按开关默认大多数场景Hold按住才录音松开即停短句、怕误触发Toggle点按开始再点按结束长段落独白一句话提示首次转录前在任意输入框比如备忘录实测一次按键 → 说话 → 松开 → 看文字落地确认粘贴目标是当前窗口而不是剪贴板。原理揭秘从按键到粘贴的完整链路体验过一遍之后再拆原理就具体多了。Handy 是典型的 Tauri 双层结构React TypeScriptTailwind CSS负责设置界面与覆盖层Rust 后端负责音频、推理与系统集成。一条录音的完整生命周期如下第 1 步全局快捷键捕获。src-tauri/src/shortcut/ 维护着两套可切换的按键监听实现——Tauri 内置的 global-shortcut 插件以及自研的 handy-keys 库。后者初始化失败时会自动回落到前者并把回落结果写回配置避免每次启动都重复试错。这种带持久化兜底的写法值得借鉴src-tauri/src/shortcut/mod.rs 中的init_shortcuts就是这段逻辑的入口。第 2 步录音与重采样。后端用cpal跨平台采集麦克风数据再经rubato重采样到 16 kHz 单声道——这是 Whisper 家族的统一输入规格。采集线程与消费方之间用 mpsc 通道传递 32 位浮点帧Cmd::Start还携带发送时间戳用于记录命令在队列里停留了多久src-tauri/src/audio_toolkit/audio/recorder.rs。第 3 步VAD 静音过滤。原始音频里说话只占一小部分src-tauri/src/audio_toolkit/vad/ 默认用 Silero VAD 把静音段裁掉参数都写在 vad/mod.rs 顶部语音起点前保留 450 msVAD_PREFILL_MS防止吞掉词首语音起点需 60 ms 确认VAD_ONSET_MS防止噪声误触发句尾拖尾离线模式 450 ms流式模式延长到 1650 ms技术要点拖尾长短直接决定最后一个词会不会被切掉。流式模型在录音期间就要出字所以它的拖尾是离线模式的 3 倍多——宁可多送一点尾部音频给模型也不截断词语。VAD 后端还通过 trait 抽象VoiceActivityDetectorSilero 之外的 earshot 等实现只需保证帧时长换算向上取整即可无损替换。第 4 步模型推理。这是两条分叉的路线由 src-tauri/src/managers/model.rs 中的EngineType区分Whisper 家族Small/Medium/Turbo/Large走transcribe-cppwhisper.cpp 生态支持 CUDA / Metal 等 GPU 加速输入是 GGML.bin或.gguf文件Parakeet V3走transcribe-rs基于 ONNX Runtime 的 CPU 推理最低要求 Intel Skylake 级 CPU官方实测中等配置i5 级别约 5 倍实时速度且自带语言检测免去手动选语言两者共用同一个转录协调器 src-tauri/src/managers/transcription.rs它负责调度音频管理器与模型管理器、应用自定义词汇、去除口头禅filler words、规范化输出。第 5 步文本后处理与粘贴。识别结果先经过文本清洗audio_toolkit/text.rs然后由 src-tauri/src/paste_tx/ 按平台执行输入macOS 用原生事件模拟Windows 有独立实现Linux 则依赖xdotool/wtype/dotool缺失时回落 enigo兼容性有限见下一节。流式覆盖层边说边看字。支持流式的模型在录音期间就会实时出字。覆盖层收到的是StreamTextEvent { committed, tentative }事件——committed是已定稿、不再改写的文本前缀tentative是模型仍可能重写的易变后缀。前端把两段分开渲染视觉上就不会出现已经确认的字突然跳变的闪烁。进阶玩法与调优模型怎么选按硬件对号入座内置模型及其体积来自 README 的模型清单模型体积定位Whisper Small487 MB轻量快有 GPU 时首选Whisper Medium492 MB (q4_1)精度/速度均衡Whisper Turbo1600 MB大模型中较快Whisper Large v31100 MB (q5_0)精度最高吃显存Parakeet V3 (int8)478 MB纯 CPU约 5 倍实时速度自动语言检测踩坑提醒没有独显的办公本直接选 Parakeet V3。Whisper 家族在无 GPU 的 CPU 上推理明显偏慢且部分 Windows/Linux 配置下偶发崩溃README 已列为已知问题CPU 机型不必在这个坑上耗时间。网络受限环境手动安装模型四步法公司内网、代理环境下自动下载失败时可以走手动通道在 Settings → About 里复制 App Data Directory 路径macOS 为~/Library/Application Support/com.pais.handy/Linux 为~/.config/com.pais.handy/在其下创建models/目录放入模型文件Whisper 的.bin/.gguf直接放Parakeet 的.tar.gz解压后目录名必须精确为parakeet-tdt-0.6b-v3-int8重启 HandySettings → Models 中该模型会显示已下载{app_data_dir}/models/ ├── ggml-small.bin # Whisper.bin/.gguf 直接放 └── parakeet-tdt-0.6b-v3-int8/ # Parakeet解压后目录名须完全一致自定义微调过的 Whisper GGML 模型同样走这个目录重启后出现在Custom Models区模型名从文件名推导my-custom-model.bin→ My Custom Model。精度调优三件套自定义词汇表在 Settings → Custom Words 中填入专业术语、人名、产品名推理时通过apply_custom_words注入提示显著提升领域词识别率口头禅过滤开启 filler word removal转录后自动剔除嗯、啊、那个之类的填充词LLM 后处理可选src-tauri/src/llm_client.rs 支持把文本送到 OpenAI 兼容端点做润色与结构化输出JSON Schema 约束还针对不同供应商处理了关闭推理模式的差异字段。注意这一步会把文本发到外部 API与完全离线定位相悖按需开启性能与内存把旋钮拧对Advanced 设置页里有几个直接影响资源占用的项Model Unload Timeout模型闲置超时后自动卸载释放显存/内存多模型切换频繁的场景调小它Recording Buffer录音缓冲大小偏大更稳、偏小延迟更低Acceleratorwhisper.cpp 侧的 GPU 后端CUDA/Metal 等NVIDIA 卡选 CUDA、Apple Silicon 选 Metal调试模式CmdShiftDmacOS或CtrlShiftDWin/Linux打开实时日志查看器排查为什么这句话说错了时先看日志再调参数平台适配与系统集成Linux三个必知点1输入工具。Wayland 下没有wtype或dotool文字就贴不进去sudo apt install wtype # Wayland # X11 则用 xdotooldotool 需把用户加入 input 组2启动依赖。录制覆盖层链接了gtk-layer-shell启动报error while loading shared libraries: libgtk-layer-shell.so.0时按发行版装libgtk-layer-shell0Debian/Ubuntu、gtk-layer-shellFedora/Arch。仍不稳定的话可用环境变量绕开HANDY_NO_GTK_LAYER_SHELL1 handy WEBKIT_DISABLE_DMABUF_RENDERER1 handy # 渲染异常时尝试3Wayland 全局快捷键走 CLI。Wayland 不允许应用自注册系统级热键官方做法是把快捷键交给桌面环境命令指向 Handy 的远程开关。Sway/i3 示例bindsym $modo exec handy --toggle-transcriptionGNOME / KDE / Hyprland 的配置路径同理命令换成对应设置项即可。此外 Handy 还监听 Unix 信号USR2pkill -USR2 -n handy即触发转录开关。踩坑提醒0.9.4 及更早版本监听SIGUSR1做远程开关而 WebKitGTK 恰好用该信号协调 JS 垃圾回收结果是录音自己开始、自己中断约每 2 分钟一次。新版已移除该监听——如果你的配置文件里还有pkill -USR1绑定务必删掉现在它会直达 WebKit 内部处理并可能直接崩溃。macOS权限与 Globe 键M 系列芯片走 Metal 加速Whisper Turbo 体验最佳Intel Mac 可考虑 Parakeet麦克风、辅助功能权限缺一不可——文字贴不进输入框时先查辅助功能权限fn / Globe 键只认苹果自家键盘fn不在标准 USB HID 规范里Apple 用厂商私有事件上报第三方键盘的 Fn 在固件层就被消化掉了macOS 收不到、Handy 也无从监听。混用键盘的用户请改用ctrl/option/shift/command组合键蓝牙耳麦录音时 macOS 会切到双向音频通道播放质量暂时下降属正常现象保持输出设备为耳机、录音输入选内置麦克风即可规避Windows装完即用Windows x64 路径最平winget 安装后授予权限即可。全局快捷键由后端按键监听库托管无需额外配置。NSIS 安装脚本见 src-tauri/nsis/。二次开发与扩展代码地图改动前先定位到对应层src/ # 前端React TS ├── components/settings/ # 每个设置项一个组件加新设置从这里入手 ├── stores/settingsStore.ts # zustand 状态与后端设置同步 ├── i18n/locales/ # 24 个语言的翻译文件 └── overlay/ # 录音覆盖层独立 webview 入口 src-tauri/src/ ├── audio_toolkit/ # 录音、重采样、VAD、文本处理 ├── managers/ # 转录/模型/音频/历史管理器 ├── shortcut/ # 双实现按键监听 └── paste_tx/ # 平台粘贴实现扩展建议加一个设置项在 src/components/settings/ 新建组件可参考ToggleSwitch等现有封装再到 src/stores/settingsStore.ts 与 Rust 侧AppSettings各补一个字段前后端通过 Tauri command 事件同步加一种语言在 src/i18n/locales/ 新建目录放translation.json仓库提供bun run check:translations脚本校验键值完整性做外部集成不必碰 UI——Handy 的单实例插件支持把 CLI 参数转发给运行中的进程--toggle-transcription、--toggle-post-process、--cancel配合--start-hidden --no-tray可实现后台常驻 任意脚本/热键守护触发的集成模式换 VAD 或换引擎VoiceActivityDetectortrait 与EngineType枚举都是面向接口设计的新增实现不需要动协调器主干踩坑提醒构建需要 Rust 平台依赖Linux 需 gtk-layer-shell 开发包详见 BUILD.md仓库用 Nix flake 组织构建依赖flake.nix 与 nix/ 是环境入口。落地建议与未来展望给你的三条可执行建议硬件对表选型有独显 → Whisper Small快或 Turbo准纯 CPU → Parakeet V35 倍实时速度意味着一句话说完几乎立刻出字先跑通再调优第一次使用只动两个参数——模型和快捷键行为Auto 模式对多数人最省心其余词汇表、填充词过滤、卸载超时等遇到具体误识别或卡顿再动Linux 用户先装输入工具再装 Handywtype/xdotoolgtk-layer-shell运行库提前就位能避开 80% 的装完不能用了项目走向来自 README Roadmap调试日志落盘、macOS Globe 键触发与按键处理重写、可选的匿名使用统计、设置系统重构以及引入 tauri-specta 增强前后端类型安全。对贡献者而言Whisper 在部分 Windows/Linux 配置下的崩溃是明确标注 Help Wanted 的问题附带调试日志参与排查是门槛最低的切入点。Handy 用Rust 音频管线 本地推理引擎 平台粘贴层证明了一件事完全离线的语音转文本在 2026 年的消费级硬件上已经是默认体验而非折中方案。它的价值不只是这个工具本身更在于提供了一份可以直接 fork 的、边界清晰的参考实现——下一个离线 你自己的模型 你自己的集成方式的组合大概率就从这个代码库长出来。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考