Handy:基于 Tauri 与 Whisper 的离线语音转文本应用

Star41
1
代码
代码
Issues
Pull Requests
项目讨论
Wiki
分析
Star41
1

A free, open source, and extensible speech-to-text application that works completely offline.

分支158Tags65
当前项目代码仓暂无内容

Handy

Discord

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

Handy 是一款跨平台桌面应用，提供简洁且注重隐私的语音转写。按下快捷键，说出你想说的话，文字即可出现在任意文本框中。一切都在你的本地电脑上完成，不会向云端发送任何信息。

为什么选择 Handy？

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

  • 免费：无障碍工具应掌握在每个人手中，而不是藏在付费墙之后
  • 开源：我们可以共同建设。按需扩展 Handy，也为更广泛的项目贡献你的力量
  • 隐私：你的声音始终留在本地。无需将音频发送到云端，即可获取转写结果
  • 简洁：一款工具，专注一件事。把你说的话转写出来，并填入文本框

Handy 并不想成为最好的语音转文字应用——它只想成为最便于 Fork 的应用。

工作原理

  1. 按下 可配置的键盘快捷键：长按开始录音，松开停止；或轻点开启/关闭录音（也提供仅长按和仅切换模式）
  2. 说出 你要说的话，保持快捷键激活状态
  3. 松开 后，Handy 使用 Whisper 处理你的语音
  4. 获取 转写文本，并将其直接粘贴到你正在使用的任意应用中

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

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

快速开始

安装

  1. 从 发布页 或 官网 下载最新版本
    • macOS：也可通过 Homebrew cask 安装：brew install --cask handy
    • Windows：也可通过 winget 安装：winget install cjpais.Handy
      注意： Homebrew cask 和 winget 软件包并非由 Handy 开发者维护。
  2. 安装应用
  3. 启动 Handy，并授予必要的系统权限（麦克风、辅助功能）
  4. 在“设置”中配置你偏好的键盘快捷键
  5. 开始转写！

开发环境搭建

有关详细的构建说明（包括各平台特定要求），请参见 BUILD.md。

集成

安装 Handy Raycast 扩展

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

源码 · 作者 @mattiacolombomc

架构

Handy 是一个 Tauri 应用，整合了以下组件：

  • 前端：React + TypeScript，搭配 Tailwind CSS 构建设置界面
  • 后端：Rust，用于系统集成、音频处理和 ML 推理
  • 核心库：
    • transcribe-cpp：基于 Whisper 系列模型（GGML/GGUF）的本地语音识别
    • transcribe-rs：基于 Parakeet 模型的 CPU 优化语音识别
    • cpal：跨平台音频 I/O
    • vad-rs：语音活动检测
    • rdev：全局键盘快捷键与系统事件
    • rubato：音频重采样

调试模式

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 以应用包形式安装时，直接调用可执行文件：

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

已知问题与当前限制

本项目正在积极开发中，并存在一些已知问题。我们希望透明地说明当前状态：

蓝牙耳机麦克风（macOS）

在 macOS 上使用蓝牙耳机麦克风录音时，蓝牙可能会切换到双向音频模式，从而导致播放质量或音量暂时下降。为避免出现这种情况，请继续将耳机用作输出设备，并在 Handy 中选择 Mac 的内置麦克风或外接麦克风。

fn 与 Globe 键快捷键（macOS）

包含 fn（Globe）键的快捷键仅适用于 Apple 键盘——也就是 Mac 的内置键盘或 Apple 外接键盘。第三方键盘上永远不会触发这些快捷键，即使该键盘正连接到同一台 Mac。

这是硬件限制，而非 Handy 的缺陷。fn 并不属于标准 USB HID 键盘规范：Apple 通过一种厂商专用用法上报该按键，而 macOS 只认可来自 Apple 设备的这类用法；第三方键盘则完全在固件中处理 Fn 键，不会向电脑发送任何事件。因此，Handy 没有可供监听的事件。

如果你会在 MacBook 键盘与外接键盘之间切换，建议改用由标准修饰键（ctrl、option、shift、command）或普通按键组合而成的快捷键。

主要问题（需要帮助）

Whisper 模型崩溃：

  • Whisper 模型在特定系统配置下会发生崩溃（Windows 和 Linux）
  • 并非所有系统都会受到影响——问题取决于具体配置
    • 如果你遇到崩溃并且是开发者，请帮忙修复并提供调试日志！

Wayland 支持（Linux）：

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

Linux 说明

文本输入工具：

在 Linux 上实现可靠的文本输入，请根据显示服务器安装相应工具：

显示服务器 推荐工具 安装命令
X11 xdotool sudo apt install xdotool
Wayland wtype sudo apt install wtype
两者均支持 dotool sudo apt install dotool（需要 input 用户组）
  • X11：安装 xdotool，以支持直接键入和剪贴板粘贴快捷键
  • Ubuntu 26.04：默认使用 Wayland 显示服务器。wtype 不可用，你需要安装 ydotool，并按照此处中的说明配置 systemd。
  • Wayland：安装 wtype（首选）或 dotool，以便文本输入正常工作
  • dotool 配置：需要将你的用户加入 input 用户组：sudo usermod -aG input $USER（然后注销并重新登录）

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

其他说明：

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

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

      发行版 需安装的包 示例命令
      Ubuntu/Debian libgtk-layer-shell0 sudo apt install libgtk-layer-shell0
      Fedora/RHEL gtk-layer-shell sudo dnf install gtk-layer-shell
      Arch Linux gtk-layer-shell sudo pacman -S gtk-layer-shell

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

  • Linux 上的录制悬浮窗默认处于禁用状态（Overlay Position: None），因为某些合成器会将其视为活动窗口。当悬浮窗可见时，它可能会抢占焦点，导致 Handy 无法将文本粘贴回触发转录的应用程序。如果你仍选择启用悬浮窗，请注意基于剪贴板的粘贴可能失败，或粘贴到错误的窗口。

  • 如果你在使用应用时遇到问题，在设置环境变量 WEBKIT_DISABLE_DMABUF_RENDERER=1 的情况下运行可能会有帮助

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

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

    GNOME：

    1. 打开 Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts
    2. 点击 + 按钮以添加新快捷键
    3. 将 Name 设置为 Toggle Handy Transcription
    4. 将 Command 设置为 handy --toggle-transcription
    5. 点击 Set Shortcut，然后按所需键组合（例如 Super+O）

    KDE Plasma：

    1. 打开 System Settings > Shortcuts > Custom Shortcuts
    2. 点击 Edit > New > Global Shortcut > Command/URL
    3. 将其命名为 Toggle Handy Transcription
    4. 在 Trigger 选项卡中，设置所需键组合
    5. 在 Action 选项卡中，将命令设置为 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 flags 从外部触发 Handy，这样 Wayland 窗口管理器或其他热键守护进程可以继续管理键位绑定：

    操作 触发方式
    切换转录 pkill -USR2 -n handy 或 handy --toggle-transcription
    切换带后处理的转录 handy --toggle-post-process

    Sway 配置示例：

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

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

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

悬浮窗与粘贴问题（Linux）：

  • 在 Linux（X11）上，录制悬浮窗窗口可能会干扰将转录文本粘贴到目标应用。
  • 解决方案： 打开 Settings > Advanced，将 "Overlay Position" 设置为 "None" 以禁用悬浮窗。
  • 如果你仍希望通过声音确认录制状态，请启用 "Audio Feedback"（同样位于 Advanced）。
  • 从旧版本升级或从其他平台导入设置的用户，可能需要手动应用此更改。

平台支持

  • 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 上测试）
  • 自动语言检测——无需手动选择语言

路线图与开发进展

我们正在积极推进若干功能与改进。欢迎贡献与反馈！

进行中

调试日志：

  • 新增将调试日志写入文件的功能，以辅助排查问题

macOS 键盘改进：

  • 支持使用 Globe 键作为转写触发键
  • 重写 macOS 的全局快捷键处理机制，未来也可能扩展到其他操作系统。

可选统计：

  • 收集匿名使用数据，帮助改进 Handy
  • 隐私优先，并提供明确的选择加入机制

设置重构：

  • 清理并重构日趋臃肿、混乱的设置系统
  • 为设置管理引入更清晰的抽象

Tauri 命令整理：

  • 抽象并整理 Tauri 命令模式
  • 调研 tauri-specta，以提升类型安全与代码组织性

验证发布签名

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

若要手动验证某个发布版本，请将 ARTIFACT 设置为你下载的文件名，将 src-tauri/tauri.conf.json 中的 pubkey 值保存到 handy.pub.b64，然后将公钥和对应的 .sig 文件从 base64 解码，并使用 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 无法自动下载模型的受限网络环境中，可以手动下载并安装这些模型。这些 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

Parakeet 模型（压缩归档）：

  • V2（473 MB）：https://blob.handy.computer/parakeet-v2-int8.tar.gz
  • V3（478 MB）：https://blob.handy.computer/parakeet-v3-int8.tar.gz

步骤 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）中的模型，因此通过其他工具下载并保存在该位置的副本无需移动即可使用。

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/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)

重要说明：

  • 对于 Parakeet 模型，解压后的目录名称必须与上文所示完全一致
  • 请勿重命名 .bin 或 .gguf 文件——请使用下载链接中的原始文件名
  • 放置文件后，重启 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 → “我的自定义模型”）

Linux 启动崩溃或不稳定

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

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

Handy 使用 gtk-layer-shell 来实现录音覆盖层，并在运行时链接该库。缺失或损坏的安装是启动失败最常见的原因，可能在窗口显示之前很早就表现为崩溃或挂起。请确保你的发行版已安装相应的运行时软件包：

发行版 需安装的软件包 示例命令
Ubuntu/Debian libgtk-layer-shell0 sudo apt install libgtk-layer-shell0
Fedora/RHEL gtk-layer-shell sudo dnf install gtk-layer-shell
Arch Linux gtk-layer-shell sudo pacman -S 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）

在某些 GPU/驱动组合下，WebKitGTK 的 DMA-BUF 渲染器可能导致窗口渲染失败或崩溃。请尝试：

WEBKIT_DISABLE_DMABUF_RENDERER=1 handy

将临时解决方法永久化

一旦找到有效的参数，请在 shell 配置文件（~/.bashrc、~/.zshenv、…）或用于启动 Handy 的桌面自启动项中导出该参数。如果你通过 .desktop 文件启动 Handy，可以在 Exec= 行前添加前缀，例如：

Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy

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

Handy 自行开始或停止录音（Linux）

Handy 0.9.4 及更早版本会监听 SIGUSR1，将其作为远程控制触发信号。WebKitGTK——Linux 版 Handy 内嵌的网页视图引擎——内部也使用同一信号来协调 JavaScript 垃圾回收，因此 GC 周期会被误判为快捷键按下：录音会自行开始，或真实的语音输入会在句子中途被截断（通常发生在使用约 2 分钟后）。参见 #1660。

请更新到较新的版本，并将任何 pkill -USR1 -n handy 快捷键绑定替换为 handy --toggle-post-process。

如何贡献

  1. 检查现有 issue，访问 github.com/cjpais/Handy/issues
  2. Fork 仓库，并创建一个功能分支
  3. 充分测试 目标平台
  4. 提交 pull request，并清晰描述所做的更改
  5. 参与讨论 - 可通过 contact@handy.computer 联系我们

我们的目标是打造一个既实用、又能供他人继续开发的工具——一个结构规范、简洁清晰并服务社区的代码库。

赞助商

我们感谢赞助方的支持，正是他们让 Handy 成为可能：

Wordcab        Epicenter        Bolt AI

相关项目

许可证

MIT License - 详见 LICENSE 文件。

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

致谢

  • Whisper 为 OpenAI 的语音识别模型
  • ggml and transcribe.cpp 提供出色的跨平台语音转文字推理/加速
  • Silero 提供出色的轻量级 VAD
  • Tauri 团队提供优秀的基于 Rust 的应用程序框架
  • 社区贡献者 帮助让 Handy 变得更好

项目介绍

一款免费、开源且可扩展的语音转文字应用，完全支持离线运行。【此简介由AI生成】

MIT Rust833提交数accessibilitycross-platformspeech-to-texttauri-v2typescriptreact应用
定制我的领域
README
9531.09 K2.82 K访问 GitHub