尧图网站建设 
如何安装部署 Handy 离线语音转文字并解决 8 个常见报错【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款免费开源、完全离线运行的语音转文字桌面应用按住快捷键说话语音就会被转录并粘贴到任意输入框音频和文字全程留在你自己的电脑上。本文带你完成安装、源码构建、首次启动配置并逐一修复新手最常碰到的 8 个问题。动手之前5 分钟环境自检先花两分钟确认环境能避开后面一半的坑。类别要求快速检查运行权限麦克风权限macOS 额外需要辅助功能权限用于把文字粘贴进其他应用系统设置中查看构建工具仅源码构建需要Rust 稳定版 Bun 包管理器 各平台的 Tauri 系统依赖cargo --version、bun --versionLinux 桌面依赖GTK3、WebKit2GTK、ALSA、Vulkan 等开发库清单见 BUILD.mdpkg-config --exists gtk-3.0 echo ok网络与空间模型下载约 0.5–1.6 GB磁盘至少预留 2 GB浏览器能否正常访问下载站Linux 文本输入工具X11 装xdotoolWayland 装wtype用于把转录结果敲进目标应用which xdotool跑起来从零到第一次启动路径一安装官方版本推荐新手大多数人不需要自己编译直接装发布版即可。# macOS通过 Homebrew 安装 brew install --cask handy# Windows通过 winget 安装 winget install cjpais.HandyLinux 用户从项目的发布页下载 AppImage 或 deb 包双击运行或sudo dpkg -i安装即可。装好后首次打开授予麦克风权限配置快捷键就可以试说了。路径二源码构建需要改代码或定制时# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy# Linux 以 Ubuntu/Debian 为例按 BUILD.md 安装系统依赖 sudo apt install build-essential libasound2-dev pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev cmake# 安装前端依赖然后启动开发模式 bun install bun run tauri dev要点说明macOS Intel 芯片需要brew install onnxruntime并在启动时带上ORT_LIB_LOCATION和ORT_PREFER_DYNAMIC_LINK1两个环境变量详见 BUILD.md。Windows 除了 Visual Studio C 构建工具还要把 CMake 和 Vulkan SDK 装好。在 Arch 等滚动更新发行版上AppImage 打包步骤可能失败failed to run linuxdeploy改用bun run tauri build -- --bundles deb只打 deb 包即可。Linux 源码构建的产物不能直接运行裸二进制src-tauri/target/release/handy缺少托盘图标、音效、VAD 模型等资源文件。正确做法是解包构建出的 deb 再安装# 从 deb 包中提取并安装到系统 cd /tmp ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz tar xzf data.tar.gz sudo cp usr/bin/handy /usr/bin/ sudo cp -a usr/lib/. /usr/lib/第一次成功启动算什么样开发模式下浏览器窗口加载出设置界面、系统托盘出现 Handy 图标说明启动成功。进入 设置 → 通用选一个麦克风和转录模型按住快捷键说一句hello能看到录音状态即为跑通。首次启动权限、模型与起不来授予权限并做初始配置启动后应用会引导你授予两个权限麦克风录音用和辅助功能把文字写回其他应用用macOS 必给。快捷键行为在设置里可选三种Hold按住录音、Toggle点按开关、Auto按住或点按均可。问题 1模型下载卡住或失败症状设置 → 模型 页面里模型一直转圈或提示下载失败。原因模型文件体积大代理、防火墙或断网都会让自动下载中断。修复打开 设置 → 关于复制App Data Directory路径Linux 通常是~/.config/com.pais.handy/macOS 是~/Library/Application Support/com.pais.handy/Windows 是%APPDATA%\com.pais.handy\。在其中手动创建models目录用浏览器把想要的模型下载到该目录Whisper 系列是单个.bin文件如ggml-small.bin、whisper-medium-q4_1.binParakeet 是.tar.gz压缩包解压后目录名必须恰好是parakeet-tdt-0.6b-v3-int8这类格式。文件名不要改放好后完全退出并重启 Handy。验证设置 → 模型 中手动放的模型显示为已下载选中后试录一句话有文字输出。问题 2Linux 启动崩溃或窗口出不来症状进程一闪就退、一直转圈不出窗口或报libgtk-layer-shell.so.0加载失败。原因Handy 在 Linux 上链接了gtk-layer-shell库负责录音悬浮窗运行库缺失是启动失败的头号原因。修复安装对应发行版的运行库Ubuntu/Debian 执行sudo apt install libgtk-layer-shell0Fedora 执行sudo dnf install gtk-layer-shellArch 执行sudo pacman -S gtk-layer-shell已安装仍报错就重装一次。仍不行就用环境变量绕过悬浮窗初始化改回普通置顶窗口HANDY_NO_GTK_LAYER_SHELL1 handy。若窗口能出但画面异常再叠加WEBKIT_DISABLE_DMABUF_RENDERER1 handyWebKit 渲染层兼容问题。确认哪个变量有效后把Execenv HANDY_NO_GTK_LAYER_SHELL1 handy写进桌面启动项或 shell 配置里长期生效。验证命令能正常弹出主窗口和托盘图标启动终端不再打印 shared libraries 报错。问题 3转录成功但文字贴不进去症状Handy 里能看到转录结果但目标应用浏览器、编辑器里什么都没有。原因Linux 上把文字写入其他应用依赖辅助工具缺失时回退方案在部分桌面环境无效Wayland 下尤其明显。修复X11 会话安装xdotoolsudo apt install xdotool。Wayland 会话安装wtypesudo apt install wtype两者都想用就装dotool并执行sudo usermod -aG input $USER后重新登录。Ubuntu 26.04 起默认 Wayland 且wtype不可用需要按 README 的说明安装ydotool并配置 systemd 服务。另外确认 设置 → 高级 里 Overlay Position 为 None悬浮窗会抢焦点导致粘贴丢失想听录音提示音就打开 Audio Feedback。验证在任意文本框触发转录松开后文字直接出现在光标处。问题 4全局快捷键没反应症状设置的快捷键按了没反应其他应用却能用同一组合键。原因Wayland 下系统级快捷键不归应用注册必须由桌面环境接管macOS 上含fn地球键的组合只在苹果自家键盘上生效。修复GNOME设置 → 键盘 → 自定义快捷键新增一条命令为handy --toggle-transcription绑定想要的组合键如SuperO。KDE、Sway、Hyprland 同理各自在自定义快捷键/配置文件里写exec handy --toggle-transcription。不想动桌面环境就用信号方式绑定pkill -USR2 -n handy它只是发信号不会杀进程。macOS 用户把快捷键改成ctrl/option/shift/command加普通键的组合。验证在任意输入框按下绑定键录音指示出现再按一下停止并出文字。问题 5macOS 源码构建后权限一直Waiting症状本地构建安装后应用提示等待辅助功能授权勾了也没用。原因本地构建用的是 ad-hoc 签名每次重新编译代码签名身份都会变系统里旧的授权记录对不上号。修复把最终构建产物装到/Applications/Handy.app退出 Handy。执行tccutil reset Accessibility com.pais.handy清除过期的辅助功能记录不影响麦克风等其他权限。重新打开应用按提示再次授权。验证授权后应用不再显示 Waiting转录文字能正常写入其他应用。官方发布版通常不需要这一步。问题 6Windows 构建报路径过长MSB3491 / FTK1011症状transcribe-cpp-sys阶段失败提示路径超过 260 字符。原因Vulkan 着色器生成器的 CMake 目录嵌套太深撞上 Windows 传统路径长度上限。修复新版transcribe-cpp已自动用短目录软链接规避先确认依赖是新的。仍报错就把 Cargo 输出目录换到短路径PowerShell 中执行$env:CARGO_TARGET_DIR C:\h然后开新终端再bun run tauri dev。验证编译继续推进产物出现在C:\h\release\下。问题 7Windows 打包阶段报 program not found症状编译到Built application at: ...\handy.exe后失败提示签名命令找不到。原因tauri.conf.json配置了只在发布 CI 环境存在的代码签名工具本地开发用不上。修复日常开发直接用bun run tauri dev不走打包。只要可执行文件、不要安装器时用bun run tauri build --no-bundle。验证命令完整跑完且target\release\handy.exe可正常启动。问题 8录音自己开始/中断Linux 老版本症状Handy 隔几分钟自己开始录音或说到一半被切断。原因0.9.4 及更早版本监听SIGUSR1作为遥控信号而 WebKitGTK 内部正好用这个信号做垃圾回收于是被误当成热键。修复升级到最新发布版。把之前绑定的pkill -USR1 -n handy换成handy --toggle-post-process——新版 Linux 已不再监听该信号旧绑定还可能直接崩掉应用。验证静置半小时无自启录音带后处理的开关由 CLI 命令正常触发。进阶与维护性能、日志、升级和备份选模型就是调性能Whisper 系列Small/Medium/Turbo/Large在有 GPU 的机器上最快但部分 Windows/Linux 环境偶发崩溃CPU 较老或没有 GPU 时选 Parakeet V3——纯 CPU 优化、自动识别语言中端硬件约 5 倍实时速度。日志与调试模式全局按CtrlShiftDmacOS 为CmdShiftD进入调试模式界面会出现实时日志和诊断项。文件日志在 设置 → 调试 → 日志目录点击打开直接定位核心音频与推理逻辑见 src-tauri/src/managers/设置页面对应 src/components/settings/debug/。提 bug 时附上版本、操作系统、CPU/GPU 型号、复现步骤和调试日志。遥控与自动化handy --toggle-transcription # 开关录音 handy --toggle-post-process # 开关录音后处理 handy --start-hidden --no-tray # 开机静默自启 handy --help # 查看全部参数这些参数在所有平台可用也是 Wayland 下做快捷键绑定的标准姿势。升级与备份升级走应用内更新器更新包签名公钥在src-tauri/tauri.conf.json里可核对手动装新包前建议整体退出旧进程。备份两样东西就够配置文件settings_store.json在 App Data 目录内和models目录。换机后原样拷回模型不用重新下载。常见问题速查现象最可能原因处理说话后没有任何文字麦克风选错或权限未给设置里切换麦克风重新授权macOS 蓝牙耳机录音时音量变小蓝牙切成了双向音频输出设备保持耳机麦克风选 Mac 内置/外接转录文字很长CPU 占用高模型太大换 Parakeet V3 或 Whisper SmallWayland 下按快捷键无反应系统快捷键被桌面环境接管按上文在 GNOME/KDE 里绑定handy --toggle-transcription社区与贡献项目目前处于功能冻结期修 bug 和稳定性优先新功能 PR 需要社区支持才会被考虑细节见 CONTRIBUTING.md。新手可以认领带good first issue标签的问题提问可走项目的 Discussions 或 Discord。参与前请先搜索已有 issue 和 PR避免重复劳动。关键词核心关键词Handy 离线语音转文字、Handy 本地语音识别长尾关键词Handy 安装教程、Handy 源码编译构建、Handy 模型手动下载、Handy Linux gtk-layer-shell 启动失败、Handy Wayland 快捷键配置、Handy macOS 辅助功能权限、Handy 日志目录位置【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何安装部署 Handy 离线语音转文字，并解决 8 个常见报错
如何安装部署 Handy 离线语音转文字并解决 8 个常见报错【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款免费开源、完全离线运行的语音转文字桌面应用按住快捷键说话语音就会被转录并粘贴到任意输入框音频和文字全程留在你自己的电脑上。本文带你完成安装、源码构建、首次启动配置并逐一修复新手最常碰到的 8 个问题。动手之前5 分钟环境自检先花两分钟确认环境能避开后面一半的坑。类别要求快速检查运行权限麦克风权限macOS 额外需要辅助功能权限用于把文字粘贴进其他应用系统设置中查看构建工具仅源码构建需要Rust 稳定版 Bun 包管理器 各平台的 Tauri 系统依赖cargo --version、bun --versionLinux 桌面依赖GTK3、WebKit2GTK、ALSA、Vulkan 等开发库清单见 BUILD.mdpkg-config --exists gtk-3.0 echo ok网络与空间模型下载约 0.5–1.6 GB磁盘至少预留 2 GB浏览器能否正常访问下载站Linux 文本输入工具X11 装xdotoolWayland 装wtype用于把转录结果敲进目标应用which xdotool跑起来从零到第一次启动路径一安装官方版本推荐新手大多数人不需要自己编译直接装发布版即可。# macOS通过 Homebrew 安装 brew install --cask handy# Windows通过 winget 安装 winget install cjpais.HandyLinux 用户从项目的发布页下载 AppImage 或 deb 包双击运行或sudo dpkg -i安装即可。装好后首次打开授予麦克风权限配置快捷键就可以试说了。路径二源码构建需要改代码或定制时# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy# Linux 以 Ubuntu/Debian 为例按 BUILD.md 安装系统依赖 sudo apt install build-essential libasound2-dev pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev cmake# 安装前端依赖然后启动开发模式 bun install bun run tauri dev要点说明macOS Intel 芯片需要brew install onnxruntime并在启动时带上ORT_LIB_LOCATION和ORT_PREFER_DYNAMIC_LINK1两个环境变量详见 BUILD.md。Windows 除了 Visual Studio C 构建工具还要把 CMake 和 Vulkan SDK 装好。在 Arch 等滚动更新发行版上AppImage 打包步骤可能失败failed to run linuxdeploy改用bun run tauri build -- --bundles deb只打 deb 包即可。Linux 源码构建的产物不能直接运行裸二进制src-tauri/target/release/handy缺少托盘图标、音效、VAD 模型等资源文件。正确做法是解包构建出的 deb 再安装# 从 deb 包中提取并安装到系统 cd /tmp ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz tar xzf data.tar.gz sudo cp usr/bin/handy /usr/bin/ sudo cp -a usr/lib/. /usr/lib/第一次成功启动算什么样开发模式下浏览器窗口加载出设置界面、系统托盘出现 Handy 图标说明启动成功。进入 设置 → 通用选一个麦克风和转录模型按住快捷键说一句hello能看到录音状态即为跑通。首次启动权限、模型与起不来授予权限并做初始配置启动后应用会引导你授予两个权限麦克风录音用和辅助功能把文字写回其他应用用macOS 必给。快捷键行为在设置里可选三种Hold按住录音、Toggle点按开关、Auto按住或点按均可。问题 1模型下载卡住或失败症状设置 → 模型 页面里模型一直转圈或提示下载失败。原因模型文件体积大代理、防火墙或断网都会让自动下载中断。修复打开 设置 → 关于复制App Data Directory路径Linux 通常是~/.config/com.pais.handy/macOS 是~/Library/Application Support/com.pais.handy/Windows 是%APPDATA%\com.pais.handy\。在其中手动创建models目录用浏览器把想要的模型下载到该目录Whisper 系列是单个.bin文件如ggml-small.bin、whisper-medium-q4_1.binParakeet 是.tar.gz压缩包解压后目录名必须恰好是parakeet-tdt-0.6b-v3-int8这类格式。文件名不要改放好后完全退出并重启 Handy。验证设置 → 模型 中手动放的模型显示为已下载选中后试录一句话有文字输出。问题 2Linux 启动崩溃或窗口出不来症状进程一闪就退、一直转圈不出窗口或报libgtk-layer-shell.so.0加载失败。原因Handy 在 Linux 上链接了gtk-layer-shell库负责录音悬浮窗运行库缺失是启动失败的头号原因。修复安装对应发行版的运行库Ubuntu/Debian 执行sudo apt install libgtk-layer-shell0Fedora 执行sudo dnf install gtk-layer-shellArch 执行sudo pacman -S gtk-layer-shell已安装仍报错就重装一次。仍不行就用环境变量绕过悬浮窗初始化改回普通置顶窗口HANDY_NO_GTK_LAYER_SHELL1 handy。若窗口能出但画面异常再叠加WEBKIT_DISABLE_DMABUF_RENDERER1 handyWebKit 渲染层兼容问题。确认哪个变量有效后把Execenv HANDY_NO_GTK_LAYER_SHELL1 handy写进桌面启动项或 shell 配置里长期生效。验证命令能正常弹出主窗口和托盘图标启动终端不再打印 shared libraries 报错。问题 3转录成功但文字贴不进去症状Handy 里能看到转录结果但目标应用浏览器、编辑器里什么都没有。原因Linux 上把文字写入其他应用依赖辅助工具缺失时回退方案在部分桌面环境无效Wayland 下尤其明显。修复X11 会话安装xdotoolsudo apt install xdotool。Wayland 会话安装wtypesudo apt install wtype两者都想用就装dotool并执行sudo usermod -aG input $USER后重新登录。Ubuntu 26.04 起默认 Wayland 且wtype不可用需要按 README 的说明安装ydotool并配置 systemd 服务。另外确认 设置 → 高级 里 Overlay Position 为 None悬浮窗会抢焦点导致粘贴丢失想听录音提示音就打开 Audio Feedback。验证在任意文本框触发转录松开后文字直接出现在光标处。问题 4全局快捷键没反应症状设置的快捷键按了没反应其他应用却能用同一组合键。原因Wayland 下系统级快捷键不归应用注册必须由桌面环境接管macOS 上含fn地球键的组合只在苹果自家键盘上生效。修复GNOME设置 → 键盘 → 自定义快捷键新增一条命令为handy --toggle-transcription绑定想要的组合键如SuperO。KDE、Sway、Hyprland 同理各自在自定义快捷键/配置文件里写exec handy --toggle-transcription。不想动桌面环境就用信号方式绑定pkill -USR2 -n handy它只是发信号不会杀进程。macOS 用户把快捷键改成ctrl/option/shift/command加普通键的组合。验证在任意输入框按下绑定键录音指示出现再按一下停止并出文字。问题 5macOS 源码构建后权限一直Waiting症状本地构建安装后应用提示等待辅助功能授权勾了也没用。原因本地构建用的是 ad-hoc 签名每次重新编译代码签名身份都会变系统里旧的授权记录对不上号。修复把最终构建产物装到/Applications/Handy.app退出 Handy。执行tccutil reset Accessibility com.pais.handy清除过期的辅助功能记录不影响麦克风等其他权限。重新打开应用按提示再次授权。验证授权后应用不再显示 Waiting转录文字能正常写入其他应用。官方发布版通常不需要这一步。问题 6Windows 构建报路径过长MSB3491 / FTK1011症状transcribe-cpp-sys阶段失败提示路径超过 260 字符。原因Vulkan 着色器生成器的 CMake 目录嵌套太深撞上 Windows 传统路径长度上限。修复新版transcribe-cpp已自动用短目录软链接规避先确认依赖是新的。仍报错就把 Cargo 输出目录换到短路径PowerShell 中执行$env:CARGO_TARGET_DIR C:\h然后开新终端再bun run tauri dev。验证编译继续推进产物出现在C:\h\release\下。问题 7Windows 打包阶段报 program not found症状编译到Built application at: ...\handy.exe后失败提示签名命令找不到。原因tauri.conf.json配置了只在发布 CI 环境存在的代码签名工具本地开发用不上。修复日常开发直接用bun run tauri dev不走打包。只要可执行文件、不要安装器时用bun run tauri build --no-bundle。验证命令完整跑完且target\release\handy.exe可正常启动。问题 8录音自己开始/中断Linux 老版本症状Handy 隔几分钟自己开始录音或说到一半被切断。原因0.9.4 及更早版本监听SIGUSR1作为遥控信号而 WebKitGTK 内部正好用这个信号做垃圾回收于是被误当成热键。修复升级到最新发布版。把之前绑定的pkill -USR1 -n handy换成handy --toggle-post-process——新版 Linux 已不再监听该信号旧绑定还可能直接崩掉应用。验证静置半小时无自启录音带后处理的开关由 CLI 命令正常触发。进阶与维护性能、日志、升级和备份选模型就是调性能Whisper 系列Small/Medium/Turbo/Large在有 GPU 的机器上最快但部分 Windows/Linux 环境偶发崩溃CPU 较老或没有 GPU 时选 Parakeet V3——纯 CPU 优化、自动识别语言中端硬件约 5 倍实时速度。日志与调试模式全局按CtrlShiftDmacOS 为CmdShiftD进入调试模式界面会出现实时日志和诊断项。文件日志在 设置 → 调试 → 日志目录点击打开直接定位核心音频与推理逻辑见 src-tauri/src/managers/设置页面对应 src/components/settings/debug/。提 bug 时附上版本、操作系统、CPU/GPU 型号、复现步骤和调试日志。遥控与自动化handy --toggle-transcription # 开关录音 handy --toggle-post-process # 开关录音后处理 handy --start-hidden --no-tray # 开机静默自启 handy --help # 查看全部参数这些参数在所有平台可用也是 Wayland 下做快捷键绑定的标准姿势。升级与备份升级走应用内更新器更新包签名公钥在src-tauri/tauri.conf.json里可核对手动装新包前建议整体退出旧进程。备份两样东西就够配置文件settings_store.json在 App Data 目录内和models目录。换机后原样拷回模型不用重新下载。常见问题速查现象最可能原因处理说话后没有任何文字麦克风选错或权限未给设置里切换麦克风重新授权macOS 蓝牙耳机录音时音量变小蓝牙切成了双向音频输出设备保持耳机麦克风选 Mac 内置/外接转录文字很长CPU 占用高模型太大换 Parakeet V3 或 Whisper SmallWayland 下按快捷键无反应系统快捷键被桌面环境接管按上文在 GNOME/KDE 里绑定handy --toggle-transcription社区与贡献项目目前处于功能冻结期修 bug 和稳定性优先新功能 PR 需要社区支持才会被考虑细节见 CONTRIBUTING.md。新手可以认领带good first issue标签的问题提问可走项目的 Discussions 或 Discord。参与前请先搜索已有 issue 和 PR避免重复劳动。关键词核心关键词Handy 离线语音转文字、Handy 本地语音识别长尾关键词Handy 安装教程、Handy 源码编译构建、Handy 模型手动下载、Handy Linux gtk-layer-shell 启动失败、Handy Wayland 快捷键配置、Handy macOS 辅助功能权限、Handy 日志目录位置【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考