Handy-完全本地的语音识别工具

一款免费、开源、可扩展的离线语音转文字应用，全程本地运行，无需联网。

Handy 是一款跨平台桌面应用，基于 Tauri（Rust + React / TypeScript） 构建，专注于简单、隐私友好的语音转写体验。 只需按下快捷键开始说话，你的语音就会被自动转换为文字并输入到当前使用的任意文本框中——完全不会将语音发送到云端。

为什么选择 Handy？

Handy 旨在填补“真正开源、可扩展的语音转文字工具”的空白。正如 handy.computer [1]所说：

•免费（Free）：无障碍工具应该属于每个人，而不是被锁在付费墙后•开源（Open Source）：一起持续构建。你可以为自己扩展 Handy，也能回馈社区•隐私（Private）：你的声音只存在于你的电脑中，转写无需上传音频•简单（Simple）：一个工具，只做一件事——把你说的话变成文本并输入到文本框

Handy 并不是想成为“最强”的语音转文字应用，而是希望成为最容易被 Fork 和定制的应用。

工作原理

1.按下可配置的键盘快捷键开始/停止录音（也支持按住说话模式）2.在快捷键激活期间说话3.松开按键后，Handy 使用 Whisper 进行语音处理4.转写后的文本会直接粘贴到你当前使用的应用中

整个流程完全在本地完成：

•使用 VAD（语音活动检测），基于 Silero 过滤静音•转写模型可自由选择：•Whisper 模型（Small / Medium / Turbo / Large），在可用时支持 GPU 加速•Parakeet V3：CPU 优化模型，性能出色，支持自动语言检测•支持 Windows、macOS 和 Linux

快速开始

安装

1.从 Releases 页面[2]或官网[3]下载安装最新版本2.按照对应操作系统的指引完成安装3.启动 Handy，并授予必要的系统权限（麦克风、辅助功能）4.在设置中配置你喜欢的键盘快捷键5.开始语音转写 🚀

开发环境搭建

如需查看包含各平台依赖在内的完整构建说明，请参考：BUILD.md[4]

架构设计

Handy 基于 Tauri 构建，整体架构如下：

•前端: React + TypeScript，使用 Tailwind CSS 构建设置界面•后端：Rust，负责系统集成、音频处理和机器学习推理•核心库：•whisper-rs：基于 Whisper 的本地语音识别•transcription-rs：基于 Parakeet 的 CPU 优化语音识别•cpal：跨平台音频输入/输出•vad-rs：语音活动检测•rdev：全局键盘快捷键与系统事件•rubato：音频重采样

调试模式

Handy 内置高级调试模式，便于开发和问题排查，可通过以下快捷键开启：

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

已知问题与当前限制

该项目仍在积极开发中，目前存在一些已知问题[5]。我们坚持对项目现状保持透明，以下是当前需要注意的限制与问题说明。

主要问题（亟需协助，Help Wanted）

Whisper 模型崩溃

•Whisper 模型在某些系统配置下会发生崩溃（主要出现在 Windows 和 Linux）•并非所有系统都会受到影响，问题与具体配置相关•如果你在使用过程中遇到崩溃，且具备开发经验，欢迎协助排查并提交调试日志

Wayland 支持（Linux）

•对 Wayland 显示服务器的支持仍然有限•文本输入功能需要额外工具才能正常工作：•wtype 或 dotool•具体安装方式请参阅下方「Linux 说明」

Linux 说明

文本输入工具

为了在 Linux 上获得稳定可靠的文本输入体验，请根据你所使用的显示服务器安装合适的工具：

补充说明：

•X11：安装 xdotool 后，可同时支持直接输入和剪贴板粘贴•Wayland：推荐使用 wtype，也可使用 dotool•dotool 配置：需要将当前用户加入 input 组，然后重新登录：sudo usermod -aG input $USER

如果未安装上述工具，Handy 将回退使用 enigo，而该方案的兼容性可能有限，在 Wayland 环境下尤其明显。

其他说明

•录音悬浮层（Recording Overlay） 在 Linux 上默认是关闭的（Overlay Position: None）•原因是某些窗口合成器会将悬浮层识别为当前活动窗口•当悬浮层显示时，可能会抢占焦点，导致 Handy 无法将转写结果粘贴回触发转写的应用•如果你仍然选择启用悬浮层，需要注意：基于剪贴板的粘贴可能会失败，或被粘贴到错误的窗口中•如果你在使用过程中遇到异常问题，可以尝试在启动应用时设置以下环境变量： WEBKIT_DISABLE_DMABUF_RENDERER=1•你可以在 Handy 之外管理全局快捷键，同时仍然通过系统信号来控制应用行为：

向 Handy 进程发送 SIGUSR2 信号，可切换录音的开始 / 停止状态。这种方式可以让 Wayland 窗口管理器或其他快捷键守护程序继续掌控按键绑定。示例（Sway）：

bindsym $mod+o exec pkill -USR2 -n handy

这里的pkill 仅用于发送信号，并不会终止 Handy 进程。

平台支持

•macOS（支持 Intel 和 Apple Silicon 芯片）•x64 Windows•x64 Linux

系统要求 / 推荐配置

以下为在本地运行 Handy 的推荐配置。如果系统配置低于要求，应用性能可能会下降。我们正在持续优化各类硬件上的性能。

Whisper 模型

•macOS：M 系列 Mac、Intel Mac•Windows：Intel、AMD 或 NVIDIA GPU•Linux：Intel、AMD 或 NVIDIA GPU•推荐系统：Ubuntu 22.04 / 24.04

Parakeet V3 模型

•仅 CPU 运行，支持广泛硬件•最低要求：Intel Skylake（第 6 代）或同级 AMD 处理器•性能表现：中端硬件可实现约 5 倍实时速度（在 i5 测试）•自动语言检测：无需手动选择语言

故障排查

手动安装模型（适用于代理用户或网络受限环境）

如果你处在代理、防火墙或受限网络环境，Handy 无法自动下载模型，可以手动下载并安装。相关 URL 可在任意浏览器访问。

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

1.打开 Handy 设置2.进入 About（关于）部分3.复制显示的 App Data Directory 路径，或使用快捷键打开调试菜单：•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 文件夹（如果尚不存在）：

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

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

步骤 3：下载模型文件

从以下链接下载所需模型：

Whisper 模型（单个 .bin 文件）

•Small (487 MB): 下载链接[6]•Medium (492 MB): 下载链接[7]•Turbo (1600 MB): 下载链接[8]•Large (1100 MB): 下载链接[9]

Parakeet 模型（压缩包）

•V2 (473 MB): 下载链接[10]•V3 (478 MB): 下载链接[11]

步骤 4：安装模型（Step 4: Install Models）

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

Parakeet 模型（.tar.gz 压缩包）

1.解压 .tar.gz 文件2.将解压后的文件夹放入 models 目录3.文件夹名称必须完全匹配以下格式：

•Parakeet V2：parakeet-tdt-0.6b-v2-int8•Parakeet V3：parakeet-tdt-0.6b-v3-int8

最终目录结构应如下所示：

{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/# 模型文件夹
│├──(model files)
│└──(config files)
└── parakeet-tdt-0.6b-v3-int8/# 模型文件夹
├──(model files)
└──(config files)

重要注意事项（Important Notes）

•对于 Parakeet 模型，解压后的文件夹名称必须与上文完全一致•不要重命名 Whisper 模型的 .bin 文件，请使用下载链接提供的原始文件名•放置好文件后，重启 Handy 以让应用识别新模型

步骤 5：验证安装（Step 5: Verify Installation）

1.重启 Handy2.打开 设置 → Models3.手动安装的模型应显示为 "Downloaded"4.选择你想使用的模型，并测试转写功能

https://github.com/cjpais/Handy?tab=readme-ov-file

References

[1] handy.computer :https://handy.computer/ [2]Releases 页面:https://github.com/cjpais/Handy/releases [3]官网:https://handy.computer/ [4]BUILD.md:https://github.com/cjpais/Handy/blob/main/BUILD.md [5]已知问题:https://github.com/cjpais/Handy?tab=readme-ov-file [6]下载链接:https://blob.handy.computer/ggml-small.bin [7]下载链接:https://blob.handy.computer/whisper-medium-q4_1.bin [8]下载链接:https://blob.handy.computer/ggml-large-v3-turbo.bin [9]下载链接:https://blob.handy.computer/ggml-large-v3-q5_0.bin [10]下载链接:https://blob.handy.computer/parakeet-v2-int8.tar.gz [11]下载链接: https://blob.handy.computer/parakeet-v3-int8.tar.gz