离线语音转文字如何落地Handy 安装、配置与排障完整指南【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款免费、开源且完全离线运行的语音转文字桌面应用按住快捷键开口说话转写结果就直接出现在你正在使用的输入框里声音和文本全程不离开你的电脑。如果你担心语音隐私或者厌倦了依赖云端网络才能工作的听写工具它值得一试。这篇文章带你从 0 到 1 走一遍先做环境体检再安装启动然后落实转写模型与系统适配最后覆盖运行时常见的翻车现场。开跑之前的环境体检Handy 前端是 React TypeScript后端是 Rust由 Tauri 框架一套基于 Rust 的桌面应用框架打包成原生窗口。要自己编译工具链必须齐只是下载安装包的话可以跳过这一节。先确认三样基础件组件作用验证方式Rust 工具链编译后端rustc --version有版本号输出Bun前端包管理器一个更快的 JS 运行时bun --version有版本号输出C/C 工具链链接音频、机器学习等原生库Linux 装build-essentialmacOS 跑xcode-select --installWindows 装 VS 2019/2022 的 C 构建工具平台差异一览macOS装好 Xcode 命令行工具即可。Intel Mac 要特别注意ONNX Runtime 没有 Intel 预编译版本需要用 Homebrew 装onnxruntime并在启动时带上ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1两个环境变量。Windows额外需要 CMake确认它在 PATH 里如果要构建 GPU 推理后端还要装 LunarG 的 Vulkan SDK装完开新终端让VULKAN_SDK生效。Linux依赖最多。以 Ubuntu/Debian 为例官方给出的完整清单在这里BUILD.md 里有 Fedora 和 Arch 的版本sudo apt update sudo apt install build-essential clang libclang-dev libevdev-dev libasound2-dev \ pkg-config libssl-dev libvulkan-dev vulkan-tools glslc spirv-headers \ glslang-tools libgtk-3-dev libwebkit2gtk-4.1-dev \ libayatana-appindicator3-dev librsvg2-dev \ libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmake验证信号rustc --version与bun --version都能打印版本号Linux 上pkg-config --exists gtk-3.0 webkit2gtk-4.1返回 0。第一步把 Handy 装起来只想用装官方发行版大多数人的最优路径是直接用打包好的安装包macOSbrew install --cask handy第三方维护的 cask非官方开发者维护Windowswinget install cjpais.HandyLinux去项目 releases 页面下载对应发行版的 deb / rpm / AppImage装好直接启动启动后按提示授予麦克风等系统权限就能进入设置页了。想魔改从源码构建克隆仓库并进入目录git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy安装前端依赖。这一步会装 React 等 JS 依赖并触发一个 postinstall 检查脚本bun install启动开发模式。首次运行要编译整个 Rust 后端等几分钟很正常bun tauri dev需要分发包时再执行生产构建它会生成各平台安装包Linux 出 deb/rpm/AppImagemacOS 出 dmgWindows 出 msibun run tauri build⚠️ Linux 源码安装有个细节src-tauri/target/release/handy这个裸二进制不能独立运行——它依赖固定路径下的托盘图标、音效、VAD 模型等资源文件。建议直接用构建产物里的 deb 安装或按 BUILD.md 的Linux Install小节把二进制和运行时库拷贝到/usr/lib/Handy/。验证信号主窗口弹出、系统托盘出现 Handy 图标、设置页能正常滚动。到这一步你已经拥有一个会呼吸但还不会转写的 Handy。第二步让它具备核心能力——转写模型落地先给权限再谈能力macOS需要麦克风权限和辅助功能Accessibility权限。后者常被忽略但没有它Handy 无法把文字敲进别的程序。Windows / Linux授予麦克风权限即可Wayland 下如果用 dotool 输入还要把用户加入input组sudo usermod -aG input $USER然后重新登录。模型放哪里首次启动时 Handy 会自动下载模型网络顺利的话你什么都不用做。处于代理或受限网络时可以手动放置找到应用数据目录。打开 设置 → 关于 页能看到路径或者按CtrlShiftDmacOS 是CmdShiftD打开调试菜单查看。常见位置macOS~/Library/Application Support/com.pais.handy/WindowsC:\Users\用户名\AppData\Roaming\com.pais.handy\Linux~/.config/com.pais.handy/在其中创建models目录把文件放进去Whisper 系列是单个.bin文件直接放进去文件名不能改.gguf文件如 Parakeet Unified EN 0.6B同样直接放进modelsParakeet V2/V3 是压缩包解压后目录名必须精确为parakeet-tdt-0.6b-v2-int8或parakeet-tdt-0.6b-v3-int8。各模型下载地址与体积见 README.md 的 Manual Model Installation 一节。重启 Handy打开 设置 → 模型手动装好的模型应显示为已下载。选模型的简单心法有 GPU 选 WhisperTurbo 速度最快没有独显或机器较老选 Parakeet V3——它纯 CPU 运行最低只需 Intel 六代 Skylake 级别中端 i5 上约 5 倍实时速度还自带语言自动检测。录制过程中覆盖层会把转写结果以流式方式打在屏幕上让你确认它真的在听。验证信号设置 → 模型 里能看到已下载的模型按住快捷键说一句话文本出现在光标处。第三步适配你的运行环境LinuxX11 与 Wayland 的文本注入Handy 把文字塞进目标程序靠的是模拟键盘输入。不同显示服务器要用不同的工具没装的话它会退回 enigo 库兜底而兜底方案在 Wayland 下兼容性很有限显示服务器输入工具安装X11xdotoolsudo apt install xdotoolWaylandwtype首选sudo apt install wtype两者dotoolsudo apt install dotool需加入input组Wayland 下怎么绑定全局快捷键Wayland 不允许应用自行注册系统级快捷键所以要在桌面环境里配置命令统一用 Handy 的 CLI 远程控制参数GNOME设置 → 键盘 → 自定义快捷键命令填handy --toggle-transcriptionKDE系统设置 → 自定义快捷键动作同上Sway / i3配置里加bindsym $modo exec handy --toggle-transcriptionHyprlandbind $mainMod, O, exec, handy --toggle-transcription。另一个选择是发信号pkill -USR2 -n handypkill这里只是投递信号不会杀掉进程。⚠️ 一个反直觉的坑老版本接受SIGUSR1触发带后处理转写但 Linux 上的 WebKitGTK 引擎内部正好用这个信号做 JS 垃圾回收绑定它会导致录音莫名其妙自己开始、甚至崩溃。不要使用pkill -USR1新版本的对应动作是handy --toggle-post-process。macOS 的两个专属坑fn地球键快捷键只在 Apple 键盘上有效——第三方键盘的 Fn 键在固件层就被消化了系统根本收不到事件这是硬件规格限制而非 Handy 的 bug。经常换键盘的话选标准修饰键组合更稳。蓝牙耳机录音时音质/音量下降蓝牙耳机在录音时切到双向音频模式导致。把输出仍留在耳机录制源选 Mac 自带或外接麦克风即可。快捷键行为可以三选一Hold 按住录音、Toggle 点按切换、Auto 两者兼容。第四步让它跑得稳、跑得快按硬件选模型是性能的第一杠杆GPU 充足上 Whisper Turbo纯 CPU 老机器用 Parakeet V3。模型越大越吃内存和磁盘按需下载不要囤积。编译期内存不足构建过程被cc1杀进程是另一码事这是编译时的峰值内存问题调低并行度CARGO_BUILD_JOBS2或临时加 swap 即可与运行时的表现无关。Windows 构建路径报错MSB3491/FTK1011/MSB6003根源是 260 字符路径上限。新版依赖已自动绕过如果仍复现把构建产物目录指到短路径再重试$env:CARGO_TARGET_DIR C:\h想让 Handy 开机就安静待命可以用启动参数组合handy --start-hidden --no-tray配合系统的自启动项。第五步它不听话时怎么办进程在窗口不出来Linux 居多按顺序试三步报error while loading shared libraries: libgtk-layer-shell.so.0时装运行时包Ubuntu/Debiansudo apt install libgtk-layer-shell0Fedorasudo dnf install gtk-layer-shellArchsudo pacman -S gtk-layer-shell。装过还不行就重装一次排除半截升级留下的坏文件。跳过 layer shell 初始化HANDY_NO_GTK_LAYER_SHELL1 handy。关闭 WebKit 的 DMA-BUF 渲染器WEBKIT_DISABLE_DMABUF_RENDERER1 handy。哪个变量救了你的启动就把它写进 shell 配置或在.desktop文件的Exec行前缀env持久化。文字没落进目标窗口Linux 的录音覆盖层会抢焦点导致粘贴回不去。打开 设置 → 高级把Overlay Position设为None再顺手打开Audio Feedback用声音确认录制状态。老用户从其他平台导入设置时记得手动改这一项。录音自己开始、自己停这是旧版本监听SIGUSR1的已知问题升级即可同时把自启动或 WM 里所有pkill -USR1的绑定换成handy --toggle-post-process。macOS 本地重建后权限卡住本地构建用的是临时签名重建后签名身份变了旧的辅助功能授权形同虚设界面停在 Waiting。装好正式包后执行osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app然后重新授予辅助功能。打包到一半失败编译成功、打包阶段报program not found那是发布流水线的代码签名命令在你本机不存在开发场景直接bun run tauri build --no-bundle跳过签名与打包。Arch 等滚动发行版上 AppImage 打包失败linuxdeploy 自带的 strip 太老处理不了新版工具链的库。deb 和 rpm 不受影响用bun run tauri build -- --bundles deb跳过 AppImage 即可。排障速查表症状可能原因快速处理bun: command not found前端工具链未装安装 Bun 后bun --version确认linker cc not found缺 C 编译工具链装 build-essential / Xcode CLT / VS Build Tools编译中途被杀编译内存峰值超限CARGO_BUILD_JOBS2或加 swapLinux 报libgtk-layer-shell.so.0缺失运行时库没装按发行版装gtk-layer-shell运行时包启动即崩 / 窗口黑屏Linuxlayer-shell 或 DMA-BUF 不兼容依次试HANDY_NO_GTK_LAYER_SHELL1、WEBKIT_DISABLE_DMABUF_RENDERER1文字贴不进目标程序覆盖层抢焦点高级设置里 Overlay Position 设为 NoneWayland 下听写无输出缺文本注入工具装wtype或 X11 的xdotool快捷键无反应Wayland 无全局快捷键 / 冲突在桌面环境里绑定handy --toggle-transcription录音自己开始或中断旧版 SIGUSR1 绑定升级删除所有pkill -USR1绑定macOS 权限卡在 Waiting本地重建后签名变更tccutil reset Accessibility com.pais.handy后重新授权Windows 构建 MSB3491/FTK1011260 字符路径上限$env:CARGO_TARGET_DIR C:\h老 CPU 上转写崩溃模型需要更新的指令集换 Parakeet V3CPU 优化下一步建议跑通之后建议做三件事到 设置 → 模型 里按自己硬件定下主力模型用CtrlShiftDmacOS 为CmdShiftD打开调试模式观察日志这是排障的第一现场把 快捷键行为 调成符合你肌肉记忆的模式。遇到解决不了的问题带着发行版、桌面环境、会话类型X11/Wayland和日志去提 issue会帮维护者快速定位。Handy 的定位从来不是功能最全的听写软件而是最容易被你拿来改的听写软件——BUILD.md 讲构建细节README.md 讲使用与已知限制后端核心在 src-tauri/src/。你的声音留在自己的机器上这就是离线语音转文字最朴素的价值。祝你第一次按住快捷键开口时文字就乖乖落到光标后面。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考