cjpais/Handy

# Handy [](https://discord.com/invite/WVBeWsNXK4) **一款免费、开源且可扩展的语音转文字应用程序，完全离线运行。** Handy 是一款跨平台桌面应用程序，提供简单、注重隐私的语音转录。按下快捷键，说话，你的文字就会出现在任何文本字段中。这一切都在你自己的电脑上发生，不会向云端发送任何信息。 ## 为什么选择 Handy？ 创建 Handy 是为了填补真正开源、可扩展的语音转文字工具的空白。正如 [handy.computer](https://handy.computer) 上所述： - **免费**：辅助工具应掌握在每个人手中，而不是被挡在付费墙之后 - **开源**：我们可以共同构建未来。为你自己扩展 Handy，并为更宏大的项目做出贡献 - **隐私**：你的声音保留在你的电脑上。无需将音频发送到云端即可获得转录 - **简单**：一个工具，一项工作。转录你所说的话并将其放入文本框 Handy 并不试图成为最好的语音转文字应用——它试图成为最容易分叉（forkable）的应用。 ## 工作原理 1. **按下**可配置的键盘快捷键开始/停止录制（或使用按住说话模式） 2. 在快捷键激活时**说话** 3. **松开**，Handy 使用 Whisper 处理你的语音 4. **获取**直接粘贴到你正在使用的任何应用程序中的转录文本 该过程完全在本地进行： - 使用带有 Silero 的 VAD（语音活动检测）过滤静音 - 转录使用你选择的模型： - **Whisper 模型**（Small/Medium/Turbo/Large），在可用时支持 GPU 加速 - **Parakeet V3** - CPU 优化模型，具有出色的性能和自动语言检测 - 适用于 Windows、macOS 和 Linux ## 快速开始 ### 安装 1. 从 [发布页面](https://github.com/cjpais/Handy/releases) 或 [网站](https://handy.computer) 下载最新版本 - **macOS**：也可通过 [Homebrew cask](https://formulae.brew.sh/cask/handy) 获取：`brew install --cask handy` 2. 安装应用程序 3. 启动 Handy 并授予必要的系统权限（麦克风、辅助功能） 4. 在设置中配置你偏好的键盘快捷键 5. 开始转录！ ### 开发设置 有关详细的构建说明，包括特定平台的要求，请参阅 [BUILD.md](BUILD.md)。 ## 架构 Handy 是作为一个 Tauri 应用程序构建的，结合了： - **前端**：React + TypeScript 配合 Tailwind CSS 用于设置 UI - **后端**：Rust 用于系统集成、音频处理和 ML 推理 - **核心库**： - `whisper-rs`：使用 Whisper 模型进行本地语音识别 - `transcription-rs`：使用 Parakeet 模型进行 CPU 优化的语音识别 - `cpal`：跨平台音频 I/O - `vad-rs`：语音活动检测 - `rdev`：全局键盘快捷键和系统事件 - `rubato`：音频重采样 ### 调试模式 Handy 包含用于开发和故障排除的高级调试模式。通过按以下键访问它： - **macOS**：`Cmd+Shift+D` - **Windows/Linux**：`Ctrl+Shift+D` ### CLI 参数 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 ``` ## 已知问题与当前限制 该项目正在积极开发中，存在一些[已知问题](https://github.com/cjpais/Handy/issues)。我们对当前状态保持透明： ### 主要问题（需要帮助） **Whisper 模型崩溃：** - Whisper 模型在某些系统配置下会崩溃（Windows 和 Linux） - 并非影响所有系统 - 问题取决于配置 - 如果你遇到崩溃并且是一名开发者，请帮助修复并提供调试日志！ **Wayland 支持 (Linux)：** - 对 Wayland 显示服务器的支持有限 - 需要 [`wtype`](https://github.com/atx/wtype) 或 [`dotool`](https://sr.ht/~geb/dotool/) 才能正常进行文本输入（有关安装，请参阅下文的 [Linux 说明](#linux-notes)） ### Linux 说明 **文本输入工具：** 为了在 Linux 上实现可靠的文本输入，请为你的显示服务器安装相应的工具： | 显示服务器 | 推荐工具 | 安装命令 | | -------------- | ---------------- | -------------------------------------------------- | | X11 | `xdotool` | `sudo apt install xdotool` | | Wayland | `wtype` | `sudo apt install wtype` | | 两者皆可 | `dotool` | `sudo apt install dotool` (需要 `input` 组) | - **X11**：安装 `xdotool` 以支持直接输入和剪贴板粘贴快捷键 - **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` 运行可能会有所帮助 - **全局键盘快捷键 (Wayland)：** 在 Wayland 上，系统级快捷键必须通过你的桌面环境或窗口管理器进行配置。使用 [CLI 标志](#cli-parameters) 作为自定义快捷键的命令。 **GNOME：** 1. 打开 **设置 > 键盘 > 键盘快捷键 > 自定义快捷键** 2. 点击 **+** 按钮添加新快捷键 3. 将 **名称** 设置为 `Toggle Handy Transcription` 4. 将 **命令** 设置为 `handy --toggle-transcription` 5. 点击 **设置快捷键** 并按下你想要的组合键（例如 `Super+O`） **KDE Plasma：** 1. 打开 **系统设置 > 快捷键 > 自定义快捷键** 2. 点击 **编辑 > 新建 > 全局快捷键 > 命令/URL** 3. 将其命名为 `Toggle Handy Transcription` 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 信号在 Handy 之外管理全局快捷键，这让 Wayland 窗口管理器或其他热键守护进程可以保留快捷键的所有权： | 信号 | 动作 | 示例 | | --------- | ----------------------------------------- | ---------------------- | | `SIGUSR2` | 切换转录 | `pkill -USR2 -n handy` | | `SIGUSR1` | 带后处理切换转录 | `pkill -USR1 -n handy` | Sway 配置示例： bindsym $mod+o exec pkill -USR2 -n handy bindsym $mod+p exec pkill -USR1 -n handy 这里的 `pkill` 只是传递信号——它不会终止进程。 ### 平台支持 - **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 上测试） - **自动语言检测** - 无需手动选择语言 ## 路线图与积极开发 我们正在积极开发 several 功能和改进。欢迎贡献和反馈！ ### 进行中 **调试日志：** - 添加调试日志到文件以帮助诊断问题 **macOS 键盘改进：** - 支持使用 Globe 键作为转录触发器 - 重写 MacOS 的全局快捷键处理，并可能也适用于其他操作系统。 **选择加入分析：** - 收集匿名使用数据以帮助改进 Handy - 隐私优先的方法，明确的选择加入 **设置重构：** - 清理和重构变得臃肿和混乱的设置系统 - 为设置管理实施更好的抽象 **Tauri 命令清理：** - 抽象和组织 Tauri 命令模式 - 研究 tauri-specta 以改进类型安全和组织 ## 故障排除 ### 手动模型安装（适用于代理用户或网络受限环境） 如果你位于代理、防火墙或受限网络环境中，导致 Handy 无法自动下载模型，你可以手动下载并安装它们。这些 URL 可以从任何浏览器公开访问。 #### 第 1 步：找到你的应用数据目录 1. 打开 Handy 设置 2. 导航到 **关于** 部分 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 -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 模型（压缩包）：** - 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 ``` **对于 Parakeet 模型（.tar.gz 归档）：** 1. 解压 `.tar.gz` 文件 2. 将**解压后的目录**放入 `models` 文件夹 3. 目录必须严格按照以下方式命名： - **Paret 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 模型，解压后的目录名称**必须**与上述完全匹配 - 不要重命名 Whisper 模型的 `.bin` 文件——使用下载 URL 中的确切文件名 - 放置文件后，重启 Handy 以检测新模型 #### 第 5 步：验证安装 1. 重启 Handy 2. 打开设置 → 模型 3. 你手动安装的模型现在应显示为“已下载” 4. 选择你想使用的模型并测试转录 ### 自定义 Whisper 模型 Handy 可以自动发现放置在 `models` 目录中的自定义 Whisper GGML 模型。这对于想要使用默认模型列表中未包含的微调或社区模型的用户非常有用。 **使用方法：** 1. 获取 GGML `.bin` 格式的 Whisper 模型（例如，从 [Hugging Face](https://huggingface.co/models?search=whisper%20ggml)） 2. 将 `.bin` 文件放入你的 `models` 目录（见上方路径） 3. 重启 Handy 以发现新模型 4. 该模型将出现在模型设置页面的“自定义模型”部分 **重要：** - 社区模型由用户提供，可能无法获得故障排除支持 - 模型必须是有效的 Whisper GGML 格式（`.bin` 文件） - 模型名称源自文件名（例如，`my-custom-model.bin` → "My Custom Model"） ### 如何贡献 1. 在 [github.com/cjpais/Handy/issues](https://github.com/cjpais/Handy/issues) **查看现有问题** 2. **Fork 仓库**并创建一个功能分支 3. 在你的目标平台上**彻底测试** 4. **提交 pull request**，并附上清晰的更改说明 5. **参与讨论** - 通过 [contact@handy.computer](mailto:contact@handy.computer) 联系我们 目标是创建一个有用的工具和供他人构建的基础——一个模式良好、简单的代码库，服务于社区。 ## 赞助商 ## 相关项目 - **[Handy CLI](https://github.com/cjpais/handy-cli)** - 原始的 Python 命令行版本 - **[handy.computer](https://handy.computer)** - 包含演示和文档的项目网站 ## 许可证 MIT License - 详见 [LICENSE](LICENSE) 文件。 ## 致谢 - OpenAI 的 **Whisper** 语音识别模型 - **whisper.cpp 和 ggml** 出色的跨平台 whisper 推理/加速 - **Silero** 出色的轻量级 VAD - **Tauri** 团队出色的基于 Rust 的应用框架 - **社区贡献者** 帮助让 Handy 变得更好 _"你对合适的语音转文字工具的搜索可以在这里结束——不是因为 Handy 完美无缺，而是因为你可以让它为你变得完美。"_

标签：ASR, GitHub开源项目, HTTP 参数枚举, Parakeet V3, Silero, VAD语音活动检测, Whisper, 可视化界面, 实时听写, 快捷键输入, 效率工具, 文字录入, 无云服务, 本地AI处理, 离线语音识别, 网络安全, 自动语音识别, 语音转文字, 跨平台桌面应用, 辅助工具, 通知系统, 通知系统, 隐私保护