企业官网建设流程全解析

Handy 离线语音转文字实战手册

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

Handy 离线语音转文字只干一件事：按快捷键、说话、文字落进当前输入框，录音与推理全程在本地完成，不经过任何云端。本文带你跑通它的安装、源码构建和运行中常见问题的排查，覆盖 macOS、Windows 与 Linux，也顺带讲清楚没有 GPU 的机器该怎么选模型。

为什么是它

• 完全本地：VAD 用 Silero 做静音过滤，识别跑在你自己的机器上，没有云端请求
• 跨平台：macOS（Intel / 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.5：28 种语言流式转写
• Whisper 系（Small/Medium/Turbo/Large GGML）：多语种，有 GPU 时走加速；自建的 GGML.bin放进目录后会自动出现在 "Custom Models" 区

高频问题与解法

🔧 环境：Linux 编译与启动依赖

Linux 启动即崩或找不到共享库。错误信息通常会直接点名libgtk-layer-shell.so.0——这是覆盖层依赖的运行时库缺失。按发行版补包：Ubuntu/Debian 装libgtk-layer-shell0，Fedora 装gtk-layer-shell，Arch 装gtk-layer-shell（源码构建再追加-dev包）。装完重启一般即恢复；若 Wayland 合成器下仍不稳定，用HANDY_NO_GTK_LAYER_SHELL=1 handy跳过 layer-shell 初始化，覆盖层会退化为普通置顶窗口。

窗口空白或渲染崩溃。常见于特定 GPU/驱动组合下的 WebKitGTK DMA-BUF 渲染路径。先试WEBKIT_DISABLE_DMABUF_RENDERER=1 handy启动验证，有效的话把变量写进 shell profile，或给.desktop文件的Exec=行加env WEBKIT_DISABLE_DMABUF_RENDERER=1前缀。

转写完文字贴不进目标窗口。Linux 的文本输入依赖辅助工具：X11 需要xdotool，Wayland 需要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 上 fn（Globe）快捷键在第三方键盘上不触发。这是硬件层限制：非 Apple 键盘的 Fn 在固件内消化，根本不产生系统事件。混用键盘的场景，换用ctrl/option/shift/command或普通按键的组合。

网络：受限环境下手动装模型

代理或防火墙环境里模型下载卡住。手动补齐即可：在应用数据目录下建models目录，把模型文件放进去——Whisper 是单个.bin，GGUF 是单个.gguf，Parakeet 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_JOBS=2压低并行度。产物 deb 可以拷到别的机器装，不必反复在同一台机器上编译。

⚡ 调优与进阶

按硬件选模型：无 GPU 选 Parakeet 系（CPU、自动语言检测），有 NVIDIA/AMD/iGPU 选 Whisper 系并在设置里挑加速器。每个模型的速度与精度评分都写在src-tauri/src/catalog/catalog.json，选之前看一眼不亏。

无头批处理适合脚本场景，Handy 暴露了--transcribe-file直接吃 16kHz 单声道 WAV，不启动 GUI：

handy --list-models # 列出已装模型 id handy --transcribe-file audio.wav --json # 输出 JSON 结果

预期输出：结构化 JSON 转写结果，可直接接进管道；模型需已安装，此路径不触发下载。

调试入口：Ctrl+Shift+D（Linux/Windows）或Cmd+Shift+D（macOS）打开 debug 模式输出详细日志；About 页可复制应用数据目录路径，方便定位日志和模型文件。

速查表

下一步

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