Handy：完全离线运行的开源语音转文字应用

一个免费、开源、可扩展的语音转文字应用，完全离线运行。

Handy 是一款跨平台桌面应用，提供简单、注重隐私的语音转写。按下快捷键，说话，你的话就会出现在任何文本框中。整个过程在你自己的电脑上完成，不会向云端发送任何信息。

为什么选择 Handy？#

Handy 的诞生是为了填补真正开源、可扩展的语音转文字工具的空白。正如 handy.computer 上所说：

• 免费：无障碍工具应属于每个人，而不是藏在付费墙后面。
• 开源：我们可以一起走得更远。为自己扩展 Handy，并为更大的事业做出贡献。
• 私密：你的声音留在你的电脑上。无需把音频发送到云端，也能获得转写结果。
• 简单：一个工具，一件事。转写你说的话，然后放进文本框。

工作原理#

1. 按下可配置的键盘快捷键：按住录制、松开停止，或轻按切换录制开关（也提供仅按住和仅切换模式）。
2. 快捷键激活时说出你的话。
3. 松开后，Handy 使用 Whisper 处理你的语音。
4. 转写文本会直接粘贴到你正在使用的任何应用中。

整个过程完全在本地进行：

• 静音通过 Silero 的 VAD（语音活动检测，Voice Activity Detection）过滤。
• 转写使用你选择的模型：
• Whisper 模型（Small/Medium/Turbo/Large），在可用时启用 GPU 加速。
• Parakeet V3 —— 针对 CPU 优化的模型，性能出色，并支持自动语言检测。
• 支持 Windows、macOS 和 Linux。

快速开始#

安装#

1. 从发布页面或官网下载最新版本。
2. macOS：也可以通过 Homebrew cask 安装：brew install --cask handy
3. Windows：也可以通过 winget 安装：winget install cjpais.Handy

注意：Homebrew cask 和 winget 包并非由 Handy 开发者维护。

Debian/Ubuntu：用 APT 安装下载的 .deb，这样所需依赖会被自动安装：

sudo apt install ./Handy_*.deb

除非依赖已经安装，否则不要使用 dpkg -i。如果你已经用了，请运行 sudo apt --fix-broken install。

1. 安装应用程序。
2. 启动 Handy 并授予必要的系统权限（麦克风、辅助功能）。
3. 在设置中配置你偏好的键盘快捷键。
4. 开始转写！

开发环境搭建#

包括平台特定要求在内的详细构建说明，请参见 BUILD.md。

赞助者#

我们感谢赞助者的支持，他们帮助 Handy 成为可能。

集成#

从 Raycast 控制 Handy——开始/停止录制、浏览转写历史、管理词典、切换模型和语言。

来源 · 作者 @mattiacolombomc

调试模式#

Handy 包含一个高级调试模式，用于开发和排障。按以下组合键进入：

• macOS：Cmd+Shift+D
• Windows/Linux：Ctrl+Shift+D

命令行参数#

Handy 支持命令行标志，用于控制正在运行的实例并自定义启动行为。这些参数在所有平台（macOS、Windows、Linux）上都可用。很大程度上这是一个测试版功能。

远程控制标志（通过单实例插件发送给已运行的实例）：

handy --toggle-transcription  # Toggle recording on/off
handy --toggle-post-process   # Toggle recording with post-processing on/off
handy --cancel                # Cancel the current operation

启动标志：

handy --start-hidden  # Start without showing the main window
handy --no-tray       # Start without the system tray icon
handy --debug         # Enable debug mode with verbose logging
handy --help          # Show all available flags

标志可以组合用于开机自启动场景：

handy --start-hidden --no-tray

macOS 提示：当 Handy 以 app bundle 形式安装时，直接调用二进制文件：

/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription

已知问题与当前限制#

这个项目正在积极开发中，存在一些已知问题。我们相信对当前状态保持透明：

蓝牙耳机麦克风（macOS）#

在 macOS 上使用蓝牙耳机的麦克风时，录制期间播放质量或音量可能会暂时下降，因为蓝牙会切换到双向音频。请让耳机保持为输出设备，并在 Handy 中选择 Mac 内置麦克风或外接麦克风，以避免此问题。

fn 和 Globe 键快捷键（macOS）#

包含 fn（Globe）键的快捷键只在 Apple 键盘上有效——你的 Mac 内置键盘或 Apple 外接键盘。在第三方键盘上，它们永远不会触发，即使该键盘连接到同一台 Mac。

这是硬件限制，而不是 Handy 的 bug。fn 不属于标准 USB HID 键盘规范的一部分：Apple 通过厂商特定的用途码上报它，macOS 只对 Apple 设备认可该用途码；而第三方键盘完全在固件中处理 Fn 键，不向电脑发送任何内容。因此没有可供 Handy 监听的事件。

如果你在 MacBook 键盘和外接键盘之间切换，请选择由标准修饰键（ctrl、option、shift、command）或普通按键组成的快捷键。

Linux 说明#

文本输入工具：

要在 Linux 上可靠地输入文本，请为你的显示服务器安装合适的工具：

• X11：安装 xdotool，用于直接输入和剪贴板粘贴快捷键。
• Ubuntu 26.04：默认使用 Wayland 显示服务器。wtype 不可用，你需要安装 ydotool，并按此处所述配置 systemd。
• Wayland：安装 wtype（首选）或 dotool，文本输入才能正常工作。
• dotool 设置：需要把你的用户加入 input 组：sudo usermod -aG input $USER（然后注销并重新登录）。

没有这些工具，Handy 会回退到 enigo，其兼容性可能有限，尤其是在 Wayland 上。

Wayland 支持（Linux）：

• 对 Wayland 显示服务器的支持有限。
• 需要 wtype 或 dotool，文本输入才能正常工作（安装方法见下方 Linux 说明）。

其他说明：

运行时库依赖（libgtk-layer-shell.so.0）：

Handy 在 Linux 上链接 gtk-layer-shell。如果启动失败并报错 error while loading shared libraries: libgtk-layer-shell.so.0，请为你的发行版安装运行时包：

在 Ubuntu/Debian 上从源码构建时，你可能还需要 libgtk-layer-shell-dev。

录制浮层在 Linux 上默认禁用（浮层位置：无），因为某些合成器会把它当作活动窗口。浮层可见时可能抢走焦点，导致 Handy 无法粘贴回触发转写的应用。如果你仍然启用浮层，请注意基于剪贴板的粘贴可能失败，或粘贴到错误的窗口。

Handy 在 Linux 上默认禁用 WebKit DMA-BUF 渲染器，但会保留显式设置的 WEBKIT_DISABLE_DMABUF_RENDERER 值。渲染相关的变通方法，请参见“故障排除 → Linux 启动崩溃或不稳定”。

如果 Handy 在 Linux 上无法可靠启动，请参见“故障排除 → Linux 启动崩溃或不稳定”。

全局键盘快捷键（Wayland）：在 Wayland 上，系统级快捷键必须通过桌面环境或窗口管理器配置。使用 CLI 标志作为自定义快捷键的命令。

GNOME：

1. 打开 设置 > 键盘 > 键盘快捷键 > 自定义快捷键
2. 点击 + 按钮添加新快捷键
3. 将名称设为“切换 Handy 转写”
4. 将命令设为 handy --toggle-transcription
5. 点击“设置快捷键”，按下你想要的组合键（例如 Super+O）

KDE Plasma：

1. 打开 系统设置 > 快捷键 > 自定义快捷键
2. 点击 编辑 > 新建 > 全局快捷键 > 命令/URL
3. 命名为“切换 Handy 转写”
4. 在“触发”标签页中设置你想要的组合键
5. 在“动作”标签页中把命令设为 handy --toggle-transcription

Sway / i3：

添加到配置文件（~/.config/sway/config 或 ~/.config/i3/config）：

bindsym $mod+o exec handy --toggle-transcription

Hyprland：

添加到配置文件（~/.config/hypr/hyprland.conf）：

bind = $mainMod, O, exec, handy --toggle-transcription

你也可以通过 Unix 信号或 CLI 标志从外部触发 Handy，这可以让 Wayland 窗口管理器或其他热键守护进程保留按键绑定的所有权：

Sway 配置示例：

bindsym $mod+o exec pkill -USR2 -n handy
bindsym $mod+p exec handy --toggle-post-process

这里的 pkill 只是发送信号——它不会终止进程。

行为变化：较早的版本也接受 SIGUSR1 来切换带后处理的转写。WebKitGTK——Linux 上 Handy 内嵌的 webview 引擎——在内部使用 SIGUSR1 来协调 JavaScript 垃圾回收，因此监听它会导致每隔几分钟出现幽灵录制并打断听写（#1660）。Handy 在 Linux 上不再监听 SIGUSR1；后处理切换仍可通过 handy --toggle-post-process 使用。请删除任何 pkill -USR1 绑定：该信号现在会直接送达 WebKit 的内部处理器，可能导致应用崩溃。

浮层与粘贴问题（Linux）：

• 录制浮层窗口可能干扰在 Linux（X11）上将转写文本粘贴到目标应用。
• 解决方法：打开 设置 > 高级，将“浮层位置”设为“无”以禁用浮层。
• 如果你仍希望有录制状态的听觉确认，请启用“音频反馈”（同样在高级中）。
• 从旧版本升级或从其他平台导入设置的用户，可能需要手动应用这一更改。

验证发布签名#

Handy 发布产物使用 Tauri 的更新器签名格式签名。公钥存储在 src-tauri/tauri.conf.json 的 plugins.updater.pubkey 下。

要手动验证发布版本，请将 ARTIFACT 设为你下载的文件名，把 src-tauri/tauri.conf.json 中的 pubkey 值保存为 handy.pub.b64，然后从 base64 解码公钥和匹配的 .sig 文件，并用 minisign 验证产物：

# Replace with the file you downloaded
ARTIFACT="Handy_0.8.1_amd64.AppImage"

python3 - "$ARTIFACT" <<'PY'
import base64, pathlib, sys

artifact = sys.argv[1]

pub = pathlib.Path("handy.pub.b64").read_text().strip()
pathlib.Path("handy.pub").write_bytes(base64.b64decode(pub))

sig = pathlib.Path(f"{artifact}.sig").read_text().strip()
pathlib.Path(f"{artifact}.minisig").write_bytes(base64.b64decode(sig))
PY

minisign -Vm "$ARTIFACT" \
  -p handy.pub \
  -x "$ARTIFACT.minisig"

成功后，minisign 会输出：

Signature and comment signature verified

不要对这些 .sig 文件使用 gpg。

故障排除#

粘贴的是之前的剪贴板内容，而不是转写文本#

如果历史记录中的转写是正确的，但 Handy 插入的是你之前复制的文本，请参见 issue #502。使用标准剪贴板粘贴方式时，Handy 会在固定延迟后恢复你之前的剪贴板内容。在负载较高时，接收应用可能在该恢复动作之后才读取剪贴板。

打开 Handy 的设置窗口，按 Cmd+Shift+D（macOS）或 Ctrl+Shift+D（Windows/Linux）显示调试选项。

在 macOS 和 Windows 上，选择剪贴板粘贴方式后，在调试中尝试“可靠粘贴（测试版）”。它使用剪贴板读取通知来延迟恢复，而不是依赖标准的固定延迟。请在出现问题的应用中测试；它仍属实验性功能。

如果“可靠粘贴”被禁用或不可用，请增大调试中的“粘贴延迟（之后）”并再次测试。它控制恢复之前剪贴板内容前的等待时间。“粘贴延迟（之前）”控制发送粘贴按键前的等待时间，解决的是操作中的另一部分问题。这些延迟设置适用于标准粘贴路径，而不是“可靠粘贴”。

如果问题仍然存在，请把 Handy 版本、操作系统、接收应用、粘贴方式、“可靠粘贴”设置以及前后延迟添加到现有 issue 中。分享日志前请隐去私密的听写文本。

手动安装模型（适用于使用代理或网络受限的用户）#

如果你处于代理、防火墙或其他受限网络环境中，Handy 无法自动下载模型，你可以手动下载并安装。这些 URL 可以从任何浏览器公开访问。

步骤 1：找到你的应用数据目录#

1. 打开 Handy 设置
2. 进入“关于”部分
3. 复制那里显示的“应用数据目录”路径，或使用快捷键：

• macOS：Cmd+Shift+D 打开调试菜单
• Windows/Linux：Ctrl+Shift+D 打开调试菜单

典型路径为：

• macOS：~/Library/Application Support/com.pais.handy/
• Windows：C:\Users\{username}\AppData\Roaming\com.pais.handy\
• Linux：~/.config/com.pais.handy/

步骤 2：创建 Models 目录#

在你的应用数据目录中，如果还没有 models 文件夹，请创建一个：

# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"

步骤 3：下载模型文件#

从下方下载你想要的模型。

Whisper 模型（单个 .bin 文件）：

• Small（487 MB）：https://blob.handy.computer/ggml-small.bin
• Medium（492 MB）：https://blob.handy.computer/whisper-medium-q4_1.bin
• Turbo（1600 MB）：https://blob.handy.computer/ggml-large-v3-turbo.bin
• Large（1100 MB）：https://blob.handy.computer/ggml-large-v3-q5_0.bin

Parakeet Unified EN 0.6B（单个 .gguf 文件，推荐）：

• Q8_0（731 MB）：https://huggingface.co/handy-computer/parakeet-unified-en-0.6b-gguf/resolve/main/parakeet-unified-en-0.6b-Q8_0.gguf

步骤 4：安装模型#

对于 Whisper 模型（.bin 文件）：

只需把 .bin 文件直接放入 models 目录：

{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin

对于 GGUF 模型（.gguf 文件）：

把 .gguf 文件直接放入 models 目录，就像上面的 Whisper .bin 文件一样。Handy 也会读取共享 Hugging Face 缓存（~/.cache/huggingface/hub）中已有的模型，因此由其他工具下载的副本无需移动即可使用。

重要说明：

• 不要重命名 .bin 或 .gguf 文件——使用下载 URL 中的确切文件名。
• 放入文件后，重启 Handy 以检测新模型。

步骤 5：验证安装#

1. 重启 Handy
2. 打开 设置 → 模型
3. 你手动安装的模型现在应显示为“已下载”
4. 选择你想使用的模型并测试转写

自定义 Whisper 模型#

Handy 可以自动发现放入 models 目录的自定义 Whisper GGML 模型。这对于想使用微调模型或默认模型列表中未包含的社区模型的用户很有用。

使用方法：

1. 获取 GGML .bin 格式的 Whisper 模型（例如来自 Hugging Face）。
2. 把 .bin 文件放入你的 models 目录（路径见上）。
3. 重启 Handy 以发现新模型。
4. 该模型会出现在“模型”设置页面的“自定义模型”部分。

重要提示：

• 社区模型由用户提供，可能无法获得故障排除支持。
• 模型必须是有效的 Whisper GGML 格式（.bin 文件）。
• 模型名称由文件名派生（例如 my-custom-model.bin → “My Custom Model”）。

Linux 启动崩溃或不稳定#

如果 Handy 在 Linux 上无法可靠启动——例如启动后不久崩溃、始终不显示窗口，或报告 Wayland 协议错误——请按顺序尝试以下步骤。

1. 安装（或重新安装）gtk-layer-shell#

Handy 使用 gtk-layer-shell 绘制录制浮层，并在运行时链接它。安装缺失或损坏是启动失败最常见的原因，可能表现为崩溃或在窗口显示之前就挂起。请确保为你的发行版安装了运行时包：

如果它已经安装但启动问题仍然存在，请尝试重新安装（例如再次运行 sudo pacman -S gtk-layer-shell），以防库文件因部分升级而损坏。

2. 禁用 GTK layer shell 浮层（HANDY_NO_GTK_LAYER_SHELL）#

如果安装库没有帮助，你可以完全跳过 gtk-layer-shell 初始化作为变通方法。在某些合成器（尤其是 Wayland 下的 KDE Plasma）上，有报告称它会与录制浮层产生不良交互。设置此变量后，浮层会回退为普通的置顶窗口：

HANDY_NO_GTK_LAYER_SHELL=1 handy

3. 配置 WebKit DMA-BUF 渲染（WEBKIT_DISABLE_DMABUF_RENDERER）#

Handy 在 Linux 上默认禁用 WebKitGTK DMA-BUF 渲染器，因为在某些 GPU/驱动组合上它可能导致空白窗口或崩溃。显式的环境变量值会被保留，包括在 Nix 包中。要明确保持渲染器禁用：

WEBKIT_DISABLE_DMABUF_RENDERER=1 handy

部分使用 WebKitGTK 2.54 的用户报告，在渲染器禁用时录制浮层会闪烁或绘制不全（#2166）。如果受影响，请尝试退出默认的变通设置：

WEBKIT_DISABLE_DMABUF_RENDERER=0 handy

这允许 WebKit 在受支持时使用渲染器，但可能重新引入上述特定 GPU/驱动的崩溃。如果发生这种情况，请移除覆盖设置或改用 =1。

在测试任一取值之前，请完全退出 Handy，包括其托盘实例。使用 --toggle-transcription 运行第二个实例不会改变正在运行进程的环境变量。

让变通方法永久生效

在真正启动 Handy 的启动器环境中设置该变量。Shell profile 中的 export 可能不适用于桌面菜单或自启动启动的情况。如果你从 .desktop 文件启动 Handy，可以在 Exec= 行前加前缀，例如：

Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy

Handy 的内置自启动会重写它生成的 desktop entry，因此编辑该条目不是持久的变通方法。对于自启动，请使用合适的会话/服务环境，或禁用 Handy 的内置自启动，用自己的启动项管理并设置所需变量。

如果某个变通方法对你有帮助，请开一个 issue 描述你的发行版、桌面环境和会话类型——这些信息有助于我们定位底层 bug。

Hyprland / Omarchy 上录制浮层空白#

如果录制浮层空白或只有边框，请完全退出 Handy，并在启用 Wayland 的情况下启动原生安装版本：

env -u HANDY_NO_GTK_LAYER_SHELL GDK_BACKEND=wayland handy

如果这样可行，请只对 Handy 的启动器应用 GDK_BACKEND=wayland。此变通方法不适用于 0.9.6 AppImage，该版本强制使用 X11。

Windows 上的 Vulkan 浮层与捕获工具（HANDY_KEEP_VULKAN_IMPLICIT_LAYERS）#

在 Windows 上，Handy 会让 Vulkan loader 跳过隐式层，以避免浮层和捕获钩子导致的崩溃（#2049）。GPU 加速仍然启用；这不会改变系统级设置。

如果你想把它用于 GPU 选择或调试工具，请完全退出 Handy（包括托盘图标），然后在同一个 PowerShell 窗口中运行以下两条命令：

$env:HANDY_KEEP_VULKAN_IMPLICIT_LAYERS = "1"
& "$env:ProgramFiles\Handy\handy.exe"

如有需要，请调整可执行文件路径。此覆盖仅适用于从该 PowerShell 会话启动的应用，不适用于开始菜单。Handy 也会保留任何现有的 VK_LOADER_LAYERS_DISABLE 值。

如何贡献#

• 在 github.com/cjpais/Handy/issues 查看现有 issue
• Fork 仓库并创建功能分支
• 在目标平台上充分测试
• 提交带有清晰变更说明的 pull request
• 加入讨论——联系 contact@handy.computer

目标是创建一个有用的工具，同时为他人提供一个可以继续构建的基础——一个模式良好、简单的代码库，服务社区。

相关项目#

• Handy CLI —— 最初的 Python 命令行版本
• handy.computer —— 含演示和文档的项目网站

许可证#

MIT 许可证——详见 LICENSE 文件。

Handy 是开源软件，但 Handy 名称、logo、图标和品牌资产不是开源的。非官方分支、重写和再分发必须使用自己的品牌，且不得暗示认可或关联。

致谢#

• OpenAI 的 Whisper 提供语音识别模型
• ggml 提供了出色的跨平台张量库
• Silero 提供了优秀的轻量级 VAD
• Tauri 团队提供了出色的 Rust 应用框架
• 帮助 Handy 变得更好的社区贡献者