Handy 离线语音转文字实战手册【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 离线语音转文字只干一件事按快捷键、说话、文字落进当前输入框录音与推理全程在本地完成不经过任何云端。本文带你跑通它的安装、源码构建和运行中常见问题的排查覆盖 macOS、Windows 与 Linux也顺带讲清楚没有 GPU 的机器该怎么选模型。为什么是它完全本地VAD 用 Silero 做静音过滤识别跑在你自己的机器上没有云端请求跨平台macOSIntel / Apple Silicon、Windows x64、Linux x64结构透明React TypeScript 前端在src/Rust 后端在src-tauri/Tauri 标准布局读起来不费劲可插拔Whisper GGML 社区模型扔进模型目录即自动识别不必改代码从零跑起来日常使用直接下载官方发布包即可macOS 也可brew install --cask handy。想改代码或换模型才需要从源码构建。前置要求只有三样Rust stable、Bun 包管理器、Tauri 系统级依赖BUILD.md按平台列了完整清单Linux 那行apt install较长照抄即可。先克隆仓库并安装前端依赖git clone https://gitcode.com/GitHub_Trending/handy11/Handy.git cd Handy bun install这一步完成后node_modules/应正常生成无网络报错。接着启动开发服务器首次会编译 Rust 后端耗时几分钟bun tauri dev预期结果终端打印 Vite 地址后弹出应用窗口首次运行按引导授予麦克风和辅助功能权限即可开始转录。打正式包用bun run tauri build产物是 deb/rpm/AppImage、dmg 或 msi。核心能力拆解️ 流式转写与实时覆盖层0.9.0 引入的 transcribe.cpp 引擎支持流式模型Parakeet Unified EN、Nemotron 3.5 等边说边出字文字实时显示在悬浮覆盖层里覆盖层同时显示录音状态和已耗时。注意部分 Linux 合成器会把这个覆盖层窗口当活跃窗口抢焦点导致文字贴不回触发应用——所以 Linux 上覆盖层默认关闭也可在 Advanced 的 Overlay Position 里手动设为 None再开 Audio Feedback 保留听觉反馈。快捷键交互模式快捷键是唯一的交互入口0.9.7 起有三种行为模式同一按键可以兼做两种Auto长按即推免说点按即切换启停新装默认Hold纯按住录音Toggle点按开始、再点按停止Wayland 下的全局快捷键需要在桌面环境里配置GNOME 自定义快捷键、KDE 全局快捷键或 Sway/Hyprland 的bindsym命令固定写handy --toggle-transcription。Handy 还提供了一批 CLI 远程控制--toggle-post-process切换带后处理的录音--cancel中止当前操作--start-hidden --no-tray适合开机自启场景。本地模型体系模型存放在应用数据目录的models子目录Linux 为~/.config/com.pais.handy/macOS 为~/Library/Application Support/com.pais.handy/。设置里的 Models 页展示完整目录选型逻辑大致是Parakeet 系CPU 优化Parakeet Unified EN 0.6B 是默认推荐中端 i5 上约 5 倍实时速度带自动语言检测Nemotron Streaming 3.528 种语言流式转写Whisper 系Small/Medium/Turbo/Large GGML多语种有 GPU 时走加速自建的 GGML.bin放进目录后会自动出现在 Custom Models 区高频问题与解法 环境Linux 编译与启动依赖Linux 启动即崩或找不到共享库。错误信息通常会直接点名libgtk-layer-shell.so.0——这是覆盖层依赖的运行时库缺失。按发行版补包Ubuntu/Debian 装libgtk-layer-shell0Fedora 装gtk-layer-shellArch 装gtk-layer-shell源码构建再追加-dev包。装完重启一般即恢复若 Wayland 合成器下仍不稳定用HANDY_NO_GTK_LAYER_SHELL1 handy跳过 layer-shell 初始化覆盖层会退化为普通置顶窗口。窗口空白或渲染崩溃。常见于特定 GPU/驱动组合下的 WebKitGTK DMA-BUF 渲染路径。先试WEBKIT_DISABLE_DMABUF_RENDERER1 handy启动验证有效的话把变量写进 shell profile或给.desktop文件的Exec行加env WEBKIT_DISABLE_DMABUF_RENDERER1前缀。转写完文字贴不进目标窗口。Linux 的文本输入依赖辅助工具X11 需要xdotoolWayland 需要wtype或dotool后者要把用户加进input组并重新登录。Ubuntu 26.04 默认 Wayland 下wtype不可用需按 README 里的说明部署ydotool。装好后在文本编辑器里做一次完整听写测试即可确认。Windows 构建报路径长度错误MSB3491 / FTK1011 / MSB6003。根因是 260 字符路径上限被 Cargo 深层 target 目录撑爆不是代码问题。transcribe-cpp0.1.3 起会自动建短 NTFS junction 绕过仍失败时把CARGO_TARGET_DIR指到C:\h这类短路径重开终端再构建。另一种情况是编译全部通过、打包阶段报program not found——那是只有发布 CI 才有的签名命令本地构建用bun run tauri build --no-bundle跳过即可。权限macOS 辅助功能与键盘本地重编后快捷键失灵、界面卡在 Waiting。本地构建使用 ad-hoc 签名每次重建代码身份都变系统里的旧辅助功能授权对不上号。把构建产物装回/Applications后执行下面的重置osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app预期结果重新打开后系统再次弹出辅助功能授权请求授予即恢复该命令只清 Accessibility 一项不影响麦克风权限。macOS 上 fnGlobe快捷键在第三方键盘上不触发。这是硬件层限制非 Apple 键盘的 Fn 在固件内消化根本不产生系统事件。混用键盘的场景换用ctrl/option/shift/command或普通按键的组合。网络受限环境下手动装模型代理或防火墙环境里模型下载卡住。手动补齐即可在应用数据目录下建models目录把模型文件放进去——Whisper 是单个.binGGUF 是单个.ggufParakeet V2/V3 是.tar.gz。注意两个硬性约束Parakeet 解压后的目录名必须精确为parakeet-tdt-0.6b-v2-int8或parakeet-tdt-0.6b-v3-int8且所有文件名不可改动。重启应用后Models 页对应条目应显示为已下载官方文件清单在 README.md 的 Manual Model Installation 小节。性能识别速度与编译内存识别偏慢或 Whisper 直接崩溃。Whisper GGML 推理在部分 Windows/Linux 配置下确有兼容性问题项目已知项且只影响特定系统遇到崩溃最稳的退路是换 Parakeet 或流式模型纯 CPU 也能跑。更老的机器先用lscpu | grep -i flags确认有无 AVX——没有的话只能上 Parakeet它要求 Intel Skylake六代或同档 AMD 起步。编译中途被 Killed。先看free -h可用内存不足 4GB 时补一个 swap 文件也可以CARGO_BUILD_JOBS2压低并行度。产物 deb 可以拷到别的机器装不必反复在同一台机器上编译。⚡ 调优与进阶按硬件选模型无 GPU 选 Parakeet 系CPU、自动语言检测有 NVIDIA/AMD/iGPU 选 Whisper 系并在设置里挑加速器。每个模型的速度与精度评分都写在src-tauri/src/catalog/catalog.json选之前看一眼不亏。无头批处理适合脚本场景Handy 暴露了--transcribe-file直接吃 16kHz 单声道 WAV不启动 GUIhandy --list-models # 列出已装模型 id handy --transcribe-file audio.wav --json # 输出 JSON 结果预期输出结构化 JSON 转写结果可直接接进管道模型需已安装此路径不触发下载。调试入口CtrlShiftDLinux/Windows或CmdShiftDmacOS打开 debug 模式输出详细日志About 页可复制应用数据目录路径方便定位日志和模型文件。速查表问题类型典型症状快速定位命令修复方向Linux 启动崩溃报错含libgtk-layer-shell.so.0ldconfig -p \| grep layer-shell按发行版装运行时包窗口空白窗口在但内容不渲染带WEBKIT_DISABLE_DMABUF_RENDERER1启动有效则持久化该变量贴字失败转写结果没进目标窗口which xdotool wtype按显示服务器装输入工具模型不显示Models 页缺条目ls ~/.config/com.pais.handy/models核对文件名与解压目录名macOS 快捷键失灵辅助功能停在 Waitingtccutil reset Accessibility com.pais.handy重置后重新授权编译 OOMKilled、cc1 被杀free -h加 swap 或限CARGO_BUILD_JOBS下一步Handy 的价值一句话概括把录音和识别整条链路留在本地交互只剩一个快捷键。想扩展功能自定义 VAD、后处理从src-tauri/src/transcription_coordinator.rs和src-tauri/src/managers/model/读起踩平某个平台专属的坑后把发行版、桌面环境、会话类型写清楚提交到仓库 issue——Whisper 兼容性和 Wayland 支持都还在持续完善中【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考